MCP#

Connect any MCP (Model Context Protocol) server and its tools appear in chat as <name>__<tool> for the model to call. This page covers adding servers, where the configuration lives, and the supported transports.

Quick start#

openprogram mcp add drawio npx -y @drawio/mcp     # add a stdio server, effective immediately
openprogram mcp list                              # status of every configured server
openprogram mcp show drawio                       # that server's tools and full schemas

mcp add options: --env KEY=VALUE (inject an environment variable into the subprocess, repeatable), --timeout (startup and per-call timeout in seconds), --disabled (write the config without starting the server). The name becomes the prefix (<name>__<tool>) for all of that server's tools.

All subcommands:

openprogram mcp token create       # create a token for the local stdio MCP server
openprogram mcp serve              # serve the authenticated MCP server over stdio
openprogram mcp list | show | add | rm | restart | enable | disable | edit | test

token create prints the newly created token as one raw line; it does not set the shell environment. Run it once, copy that line, and bind it to the serving process before serve:

openprogram mcp token create
export OPENPROGRAM_MCP_TOKEN="<paste the token printed above>"
openprogram mcp serve

If the token already exists, reuse the token you saved instead of running token create again. serve rejects a missing or mismatched OPENPROGRAM_MCP_TOKEN.

• rm stops the server and deletes its config; enable / disable toggle it (disable keeps the config).
• edit is retained only as a compatibility command and reports that raw config editing was removed because it exposed stored secrets. Use add / rm or the MCP settings page; add covers stdio servers.
• test spins the server up with a throwaway config and confirms it returns a tool list, without writing anything to disk.

The management commands talk to the resident OpenProgram background worker; if it is not running, start it with openprogram worker start (check with openprogram status).

Configured MCP servers connect in the background when the worker starts. The App and core API stay available while an optional server connects or waits for OAuth. Until that server is ready, its remote tools are unavailable; mcp list and the MCP settings page report its actual status. Each server keeps its configured startup and call timeouts.

Where the config lives#

~/.openprogram/mcp_servers.json (with --profile <name>, ~/.openprogram-<name>/mcp_servers.json). Format:

{
  "servers": {
    "drawio": {
      "type": "local",
      "command": ["npx", "-y", "@drawio/mcp"],
      "env": {},
      "enabled": true,
      "timeout_seconds": 30
    },
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp",
      "auth": {"kind": "oauth", "client_name": "OpenProgram"},
      "enabled": true
    }
  }
}

Transports and auth#

auth.kind supports none / bearer (a token field) / oauth (OAuth 2.1 PKCE; servers with dynamic client registration work with zero config — only servers requiring a pre-registered client need client_id / client_secret).

OAuth sign-in happens once#

The first time an OAuth server connects, OpenProgram opens the consent page in your browser and captures the redirect on a localhost callback. Everything the flow produced — access and refresh tokens, the dynamic client registration, and the discovered authorization endpoints — is persisted to ~/.openprogram/mcp_tokens/<server>.json (mode 0600). Every later connection, including after a worker restart, reuses the stored token; when it has expired, the refresh token renews it silently in the background. The browser only reappears when the refresh token itself is rejected (revoked or expired server-side) — the management UI then shows the server as needing re-authentication. To switch accounts or start over, POST /api/mcp/servers/{name}/auth/clear wipes the stored state and restarts the server.

Beyond tools, MCP's other two primitives — resources and prompts — are also exposed to the model through built-in meta tools (see mcp_meta in Built-in tools).