Model Context Protocol

Connect your agent (MCP)

Once data is flowing, your own AI agents query the company brain over a read-only MCP server the instance already exposes at POST {PUBLIC_BASE_URL}/mcp (Model Context Protocol, JSON-RPC 2.0 over Streamable HTTP). On a local install the endpoint is http://localhost:4000/mcp; on a real deployment it is your public https API origin. The Agents page in the console shows the exact URL for your instance.

The agent reads under this workspace's row-level security, through the same recall layer the console Ask bar uses. It is read-only: an agent can search and query, never mutate, and never touches your provider APIs directly. The MCP server runs no ConnectAI inference: it returns the retrieved substrate (raw passages, facts, entities) with per-source citations, and your agent (Claude, Codex, Cursor) composes the answer.

flowchart LR
  accTitle: How an agent reaches the brain
  accDescr: Your agent authenticates with a PAT or OAuth and calls the read-only MCP endpoint, which runs through the recall layer with row-level security and governed-raw egress over the company brain.
  AG["Your agent<br/>PAT or OAuth"] --> EP["POST /mcp<br/>read-only, JSON-RPC"]
  EP --> RL["Recall layer<br/>RLS + governed-raw egress"]
  RL --> B["Company brain"]

The read-only tool catalog

The MCP server exposes six read-only tools:

Tool	What it does
`search`	Ranked raw passages from connected sources, with per-source citations and links.
`list_sources`	The connected sources (provider and sync status) for this workspace.
`get_entity`	Structured facts about a person, company, deal, project, or topic.
`query_facts`	Look up current derived facts by key, entity type, or value.
`whats_changed`	Facts that changed (new or superseded) since a given time.
`structured_query`	A structured count, aggregate, or ranking over the connected sources.

Authentication: a Personal Access Token

The headless-friendly path is a Personal Access Token (PAT), so the agent never needs a browser sign-in. In the console, open Agents, give the token a name, and create it. The cmcp_... value is shown once: copy it then. Revoking it on the same page cuts the agent off immediately.

On self-host, minting a token requires no paywall: leave BILLING_ENABLED unset (the default). If you set it to true, token minting applies the cloud paywall and returns 403 subscription_required.

Point a client at the brain

For a client that speaks remote MCP (for example through mcp-remote):

jsonc

{
  "mcpServers": {
    "connectai": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://your-instance.example.com/mcp",
        "--header", "Authorization:${AUTH}"
      ],
      "env": { "AUTH": "Bearer cmcp_your_token_here" }
    }
  }
}

Or call it directly to confirm access (this is exactly what an agent does):

bash

curl -s -X POST https://your-instance.example.com/mcp \
  -H "Authorization: Bearer cmcp_your_token_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# -> the read-only tool catalog. A revoked or absent token returns 401.

The Accept: application/json, text/event-stream header is required. The MCP Streamable HTTP transport returns 406 Not Acceptable to a client that does not advertise both content types. Real MCP clients set this themselves; a hand-rolled curl must include it.

Governed-raw egress

The agent receives the matched raw chunk text along with per-source citations and breadcrumb links, so it can quote and cite the actual source line. This is the owner pointing their own agent at their own brain, scoped to their own workspace by row-level security (the owner reading their own data). Storage stays governed: the raw is encrypted at rest in a key-separated zone, isolated per workspace, retention controlled, and one-tap purgeable. There is no separate egress toggle to enable.

OAuth for third-party agent apps (advanced)

For agents that should do a proper per-user OAuth handshake instead of sharing a token (dynamic client registration plus an authorize and consent screen), the instance also ships a full OAuth flow, dark by default behind MCP_OAUTH_ENABLED. When enabled, the API advertises the authorization server through standard discovery documents:

bash

curl -fsS https://your-instance.example.com/.well-known/oauth-authorization-server
curl -fsS https://your-instance.example.com/.well-known/oauth-protected-resource
curl -fsS https://your-instance.example.com/.well-known/jwks.json

An MCP client discovers the authorization server from these documents, runs the OAuth flow (PKCE, S256), and then issues tools/list and tools/call against the brain. The PAT path covers the single-operator self-host case; the OAuth flow is the multi-client path.