sidebar_position: 5 title: MCP Server description: Expose Ovation's AI agent tools to external AI clients via the Model Context Protocol

Ovation MCP Server

Ovation ships an MCP server that lets external AI clients — Claude Desktop, Claude Code, Cursor, hosted bots — call the same 200+ agent tools that power the in-app assistant. The MCP server is a thin protocol adapter on top of the existing API: all business logic and authorization stay in Ovation, and authentication uses standard Ovation API keys.

How authorization works

The MCP server applies two authorization gates on every tool call:

  1. MCP tool allowlist — per API key, you choose which subset of the agent tool catalog the key may invoke through MCP.
  2. RBAC — when the tool calls the underlying Ovation API endpoint, the key's normal rbac_grants permissions are enforced as usual.

The MCP allowlist can only ever narrow the surface; it can never grant more than the key's RBAC permissions already allow.

Configuring a key for MCP

  1. Open Organization Settings → Integrations → API Keys → Create API Key.
  2. Set RBAC permissions as usual.
  3. Expand MCP tool access and choose either:
    • Allow every MCP tool (still RBAC-gated), or
    • A specific list of tools, grouped by category and operation type.
  4. Optionally restrict by Allowed Origins / IPs.
  5. Click Create Key and copy it once.

Running the server

The MCP server ships as @ovation/mcp and supports two transports.

stdio — local AI clients

Configure your AI client to spawn the binary. Example claude_desktop_config.json:

{
  "mcpServers": {
    "ovation": {
      "command": "node",
      "args": ["/abs/path/to/Ovation/apps/mcp/dist/server.js", "--transport=stdio"],
      "env": {
        "OVATION_API_BASE_URL": "https://api.ovationpms.com",
        "OVATION_API_KEY": "ov_...",
        "OVATION_WORKSPACE_ID": "00000000-0000-0000-0000-000000000000"
      }
    }
  }
}

OVATION_WORKSPACE_ID is optional; if omitted, the server falls back to the first workspace in the API key's organization.

Streamable HTTP — remote / hosted clients

node apps/mcp/dist/server.js --transport=http
# or via npm
npm --workspace @ovation/mcp run dev:http

Bind config: MCP_HTTP_PORT (default 8090), MCP_HTTP_HOST (default 127.0.0.1). Auth is per request — every POST /mcp call must include x-api-key: ov_.... An optional x-workspace-id: <uuid> overrides the default workspace.

curl -X POST http://localhost:8090/mcp \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: ov_...' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Troubleshooting

tools/list returns an empty array. The API key has no tools in its MCP allowlist. Open the key in the UI and add tools.

Tool call fails with a 403 from the API. The MCP allowlist permits the tool, but the key's RBAC permissions don't. Grant the matching permission (e.g., invoices.create) or remove the tool from the allowlist.

MCP context fetch failed (401). The API key was revoked or rotated. Regenerate it.

Write tools appear with a [WRITE — confirm before invoking] prefix in the description. That's intentional: it surfaces the tool's requires_confirmation flag to MCP clients that prompt before calling write tools.