Black Candle Wiki / OpenMGMT / AI access through the MCP server
AI access through the MCP server
What it exposes
openmgmt-mcp serves the same tool registry as the local stdio MCP transport, over MCP streamable HTTP at POST /mcp. A remote assistant can list projects and tasks, query the board state, and make non-destructive changes — created and completed tasks flow through the normal sync pipeline like any other write.
The remote permission set is reads plus non-destructive writes. Destructive tools are never exposed over the network, even if the server's AI settings would allow them locally. Every tool call and auth decision is appended to the mcp_audit_log table in the replica's database (caller, timestamp, tool, success) — local to the replica, never synced.
The public server lives at https://openmgmt.blackcandletech.com/mcp, rate-limited to 120 requests per minute per IP. /health is the only unauthenticated endpoint.
Connect with OAuth
Every /mcp request needs a Bearer validated against the issuer's /oauth/userinfo endpoint (https://auth.blackcandletech.com); the stable authd user id becomes the audit caller.
Native clients use standard OAuth dynamic client registration with PKCE S256 — the same flow the desktop and Android apps use. For scripts and personal integrations, mint a personal access token in the website's Dashboard → Tokens section instead of reusing an interactive session.
Token scopes
The token's granted scope is enforced per request, before tool dispatch:
| Scope | MCP access |
|---|---|
identity (or empty, for pre-scope issuers) |
Full access — every existing OAuth client behaves exactly as before |
openmgmt:tasks:read |
Read-only tools (list_tasks, query_tasks, get_board_state, …) |
openmgmt:tasks:write |
All tools (write implies read) |
anything else (e.g. courier:messages:read) |
No MCP tool access — every call is rejected with 403 |
Multi-scope tokens (space-delimited per RFC 6749) grant the union of their scopes. The read/write classification reuses the AI tool registry, so scopes can never drift from it, and scope denials are recorded in the audit log with caller, scope, and tool — never token material.
One caveat: successful userinfo validations are cached for five minutes, so revoking a token or narrowing its scope takes up to five minutes to reach the MCP server.
Next steps
- Getting started with OpenMGMT — the app itself.
- Syncing across devices — how writes converge across replicas.