Connect an Agent (MCP)

A hosted nest speaks the Model Context Protocol (MCP), so any MCP-capable AI agent — Claude Desktop, Claude Code, Cursor, and others — can connect and pull governed context in real time, or (with write access) create and update it. This page covers the endpoint shapes, auth, and the tools an agent gets. For the protocol internals see MCP Server.

Endpoint URLs

MCP is JSON-RPC over HTTP (Streamable HTTP — always POST, even initialize and tools/list). Two scopes:

Replace <host> with your server's address (e.g. http://localhost:3838 for a local instance, or your PUBLIC_BASE_URL). Point the agent's MCP client at the per-nest URL to work inside one nest.

Authentication

Send a cnst_ API key as a bearer token:

Authorization: Bearer cnst_<token>

Mint one from the Connect dialog (a user-level key) or POST /auth/keys. A key scoped to a nest (nest_id) is rejected on any other nest's MCP path — good for a locked-down service agent. See Authentication & API Keys.

The official PromptOwl deployment can also connect with a short-lived service ticket (scope: "mcp", HS256-signed) instead of storing a key — see the same authentication page. On self-hosted servers you use a cnst_ key.

The transport is read-tier. Because MCP is always POST, the per-nest gate admits any credential with read access; each mutating tool re-checks its own permission inside the handler (create/edit via stewardship, approve/reject via reviewer rights, sharing/steward/sync via their own admin checks). Gate rejections come back as a JSON-RPC error envelope (code -32000) with an actionable reason — key scoped to a different nest, server suspended, license required, or nest not found / no access — so the client can surface why a connection failed.

The tools an agent gets

Every connected agent gets the context_* tool family. The core retrieval and authoring tools:

Governance tools are also present: context_stewards, context_assign_steward, context_submit_review, context_approve, context_reject, context_review_queue, context_my_drafts, context_request_deletion, context_deletion_queue, context_resolve_deletion, context_share_nest, and context_grant. Server-admins additionally get context_unsynced_list and context_sync_folder.

When the workflow plane is enabled (FEATURE_WORKFLOW_PLANE=true) the agent is also offered workflow_* tools to build and run governed workflows.

What an agent can and can't read

Under stewardship, the tools only ever return the approved version of a node — draft text on disk is invisible to search, query, get, and export. A node with no approved version yet reads as "not available to AI". This is the same governance gate the REST retrieval routes enforce, so an agent connected over MCP sees exactly the blessed slice of context.

Quick connect (Claude Desktop / Cursor style)

Add an MCP server pointing at your per-nest URL with the bearer header, e.g. conceptually:

{
  "mcpServers": {
    "my-nest": {
      "url": "https://<host>/nests/<nestId>/mcp",
      "headers": { "Authorization": "Bearer cnst_<token>" }
    }
  }
}

The server's Connect dialog generates a ready-to-paste setup prompt and a downloadable .env, which is the reliable way to wire a specific client.

See also

• MCP Server — the MCP protocol surface in depth
• Authentication & API Keys — cnst_ keys and service tickets
• Hosted Nest — everything the hosted nest adds
• REST API Reference — the HTTP retrieval routes behind the same context

Sources

• src/mcp/tools.ts (Community server repo) — the TOOL_DEFINITIONS list and per-tool handlers (the context_* and workflow tools, plus their gating).
• API.md (Community server repo) — §9 MCP: the /nests/:id/mcp and server-level /mcp transport, read-tier semantics, JSON-RPC denials, and the PromptOwl native service-ticket connection.