Ontology MCP Server

Corveil exposes the organizational knowledge graph as a remote MCP server at /mcp/ontology. Any MCP-aware client (Claude Code, Codex CLI, ChatGPT Desktop, Cursor) can be pointed at it, authenticate with a virtual API key, and call ontology_lookup / ontology_search / ontology_related against the entities, meetings, decisions, and people the gateway has already indexed for your organization.

The same three primitives are also available inside Corveil chat as built-in tools — no Connect step. This integration page is for hooking them up to an external client.

One endpoint for everything

Corveil also serves all of its first-party tools from a single unified endpoint at /mcp, so an agent configures one connection instead of three. The tools arrive as three namespaces:

• ontology_* — the knowledge-graph reads documented on this page.
• insights_* — generated summaries, recommendations, and auto-built user profiles.
• control_* — operate Corveil itself: models, keys, guardrails, prompts, teams, org settings. Mutating, and destructive operations require an explicit confirm: true.

Which namespaces you receive depends on how you authenticate. A virtual API key (X-Corveil-Key / x-api-key) or a dashboard session gets all three. An OAuth/DCR client gets ontology_* only — the scopes issued to OAuth clients are read-only and carry no control access, so a browser-consented connector can never mutate your configuration. Tools you are not entitled to are absent from tools/list and refused on tools/call.

Since one connection can carry well over a hundred tools, append ?ns= to narrow it — e.g. /mcp?ns=ontology,insights — or send an X-Corveil-MCP-Namespaces header. Narrowing never grants a namespace your credential lacks.

POST https://your-corveil-host/mcp
X-Corveil-Key: sk-citadel-your-key-here
Content-Type: application/json

The per-surface endpoints below (/mcp/ontology, /mcp/insights, /mcp/control) continue to work unchanged, each serving its single namespace — existing client configurations do not need to change. Point new clients at /mcp.

Prerequisites

• A running Corveil instance with the ontology feature enabled for your organization
• A Corveil virtual API key (sk-citadel-...) — create one under Corveil → Settings → API Keys
• An MCP-aware client that supports Streamable HTTP transport with a custom header

Endpoint & Auth

Streamable HTTP transport. Authenticate with the X-Corveil-Key header. Org scoping is by construction — the key's organization is the only data the server can return; a cross-org probe returns an empty result, not an error.

POST https://your-corveil-host/mcp/ontology
X-Corveil-Key: sk-citadel-your-key-here
Content-Type: application/json

The three primitives

• ontology_lookup — "tell me about X." Resolves an entity by name (with optional entity_type) or by entity_id, and returns the synthesized context bundle: properties, 1-hop relationships, identity records, and source-event count.
• ontology_search — open-ended search with optional filters. Accepts query, an entity_types[] filter (e.g. ["Meeting", "Decision"]), and a time_range object with since / until ISO-8601 bounds.
• ontology_related — the 1..N-hop neighborhood of an entity. Accepts an entity_id (preferred) or name+entity_type and an optional depth (default 1, max 5).

Eight back-compat tools also remain registered for callers that already use the legacy names (ontology_entity, ontology_context, ontology_evidence, ontology_timeline, ontology_event, ontology_ask, ontology_stats, ontology_decisions, ontology_policies, ontology_graph). New code should prefer the three primitives.

Claude Code (~/.config/claude-code/mcp.json)

{
  "mcpServers": {
    "corveil-ontology": {
      "transport": {
        "type": "http",
        "url": "https://your-corveil-host/mcp/ontology",
        "headers": {
          "X-Corveil-Key": "sk-citadel-your-key-here"
        }
      }
    }
  }
}

Codex CLI (~/.codex/config.toml)

[mcp_servers.corveil_ontology]
url = "https://your-corveil-host/mcp/ontology"
http_headers = { "X-Corveil-Key" = "sk-citadel-your-key-here" }

Verifying the connection

# tools/list returns the three primitives plus the back-compat tools.
curl -sS https://your-corveil-host/mcp/ontology \
  -H "X-Corveil-Key: sk-citadel-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Connect without an API key (OAuth + Dynamic Client Registration)

Corveil's MCP surface also speaks OAuth 2.0 + RFC 7591 Dynamic Client Registration, so MCP clients that ship native OAuth support (Claude Desktop, Continue, Codex CLI >= 0.4, ChatGPT Desktop) can connect without ever seeing an sk-citadel-... key. The user clicks Connect in their MCP client, a browser opens to a Corveil consent screen, they approve, and the client is authorized — same dance Shell CRM customers already do.

The X-Corveil-Key path above stays as-is for headless clients and CI; OAuth is purely additive.

1. In the MCP client's "Add remote server" dialog, paste your Corveil host URL (e.g. https://your-corveil-host/mcp/ontology) and leave the API-key field empty.
2. The client hits /.well-known/oauth-protected-resource on your host, discovers the authorization server, registers itself via POST /mcp/oauth/register, and opens a browser to the consent screen.
3. If you're not already signed into Corveil, you'll bounce through WorkOS login first. The consent screen then shows mcp.read and mcp.tools — the only scopes Corveil grants to DCR clients today. Approve and you're redirected back to the client with an authorization code; it exchanges that for a bearer token automatically.
4. Authorize every authorized client from Settings → Connected MCP Clients. Revoking immediately kills all outstanding bearer tokens for that client; the user has to re-register and re-approve to reconnect.

Discovery + token endpoints, for reference:

# RFC 8414 authorization-server metadata
curl -sS https://your-corveil-host/.well-known/oauth-authorization-server | jq .

# RFC 9728 protected-resource metadata (points at the same authorization server)
curl -sS https://your-corveil-host/.well-known/oauth-protected-resource | jq .

# Subsequent /mcp/ontology calls use the issued bearer in place of X-Corveil-Key
curl -sS https://your-corveil-host/mcp/ontology \
  -H "Authorization: Bearer crv_at_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Notes: PKCE (S256) is mandatory; public clients receive a token without a client secret (PKCE-only); access tokens last 1 hour and refresh tokens last 30 days with rotation on every use.

Rate limit & observability

Requests share the per-key RPM/TPM rate limit applied to every /v1/* and /mcp/* surface — bursting from Claude Desktop will eventually hit the same 429 your other API key traffic would. The endpoint sits under the same global auth + key throttle as /v1/messages and /v1/responses.

The MCP per-tool rate-limit (mcp_rate_limits) and per-call mcp_audit_logs rows fire on the in-app chat built-in path (which goes through the gateway's MCP dispatch layer). They do not currently fire on the remote streamable transport — that path is direct streamable HTTP to the in-process MCP server, the same shape as /mcp/insights. Prefer the in-app chat surface when you need per-tool granularity or per-call audit attribution; reach for the remote endpoint when you want an external MCP client to read the graph alongside its other tools.

Troubleshooting

• 401 from /mcp/ontology: the X-Corveil-Key is missing, malformed, or has been revoked. Re-issue under Settings → API Keys.
• Empty results for a known entity: the entity is in another org. Cross-org probes return empty by RLS — verify the key's org is the one that owns the data.
• 404 from /mcp/ontology: the host is running a build that predates ontology support. Update to a build that includes the /mcp/ontology endpoint.