VOCION
Get a demo
docs/build/mcp.md

MCP

Vocion is an MCP server in two shapes: hosted at https://<host>/api/mcp for assistants and integrations, and local over stdio for authoring a workspace from an IDE.

Connect Claude or ChatGPT

The hosted endpoint signs in with OAuth 2.1 (PKCE), discovered from the URL alone.

  • claude.ai / Claude Desktop: Settings → Connectors → Add custom connector → https://<host>/api/mcp.
  • Claude Code: claude mcp add --transport http vocion https://<host>/api/mcp, then /mcp to sign in.
  • ChatGPT: developer mode → Connectors → add the same URL.
  • Cursor: .cursor/mcp.json → { "mcpServers": { "vocion": { "url": "https://<host>/api/mcp" } } }.

The client registers itself (/oauth/register), sends you to the app's consent page (/dashboard/connect), and you approve for the workspace you are in. The result is a vcn_live_ token with role member, valid 30 days with no refresh; it shows under Developers and revoking it cuts the client off. Approve again from another workspace for another token. Connected from your personal workspace, ask_workspace reaches every workspace you belong to through your assistant.

Anything that can send a header can skip OAuth: Authorization: Bearer vcn_live_….

What it can do

The hosted server exposes the workspace's records, knowledge, missions, workflows, automations, review queue and notifications, plus the agent tools in scope (ask_workspace, search_knowledge, propose_action…). Everything runs with the token's permissions; a record the person couldn't open reads as not found. The full list is in MCP tools.

Local (stdio) for authoring

claude mcp add vocion -- npm --prefix /abs/path/to/vocion-core run mcp:serve

Environment: VOCION_ORG_ID (the workspace), WORKSPACE_PATH, WORKSPACE_AUTO_APPLY (default on), WORKSPACE_AUTO_COMMIT, VOCION_MCP_AGENT_SLUG (the agent tools run as; default the lead). The stdio server adds the disk-backed tools — workspace_get, workspace_write_skill|playbook|mission|agent|object_type, workspace_diff, workspace_apply — which the hosted endpoint doesn't have.