# 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](https://nest.promptowl.ai/d/promptowl-documents/protocol/mcp-server).

## Endpoint URLs

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

| Scope | URL shape | What it reaches |
|---|---|---|
| **Per-nest** | `https://<host>/nests/<nestId>/mcp` | One nest — its documents and governance tools. |
| **Server-level** | `https://<host>/mcp` | Cross-nest: a read index plus two bootstrap writes (`nest_create`, `context_create`). |

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](https://nest.promptowl.ai/d/promptowl-documents/protocol/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:

| Tool | What it does |
|---|---|
| `context_init` | Load the vault's `CONTEXT.md` (operating instructions). Call this **first** in every conversation. |
| `context_overview` | A complete map of the vault — node count, types, tags, and a title + snippet per node. |
| `context_search` | Full-text keyword search across content, titles, tags, and metadata. |
| `context_query` | A structured selector query (`#tag`, `type:X`, `[[Title]]`, `scope:X`, combined with `+AND`, `\|OR`, `-NOT`), with graph traversal `hops`. |
| `context_get` | The full content of one node by title or id. |
| `context_list` | Browse contents with `type` / `tag` / `status` / `limit` filters. |
| `context_resolve` | Run a selector and return full node content within a token budget. |
| `context_export` | The entire nest as one markdown bundle (token-budgeted). |
| `context_table_query` | Deterministic row lookup against a TABLE (CSV) node. |
| `context_comments` | The review comments/annotations on a document. |
| `context_create` | Create a new node. Title must be unique across the nest. |
| `context_update` | Update a node — replace/append content, set tags, move lifecycle. |
| `context_delete` | Delete a node by title or id. |
| `context_move` | Move a node to a different folder (id changes; history follows). |
| `context_versions` | A node's version history and which version is approved. |

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:

```jsonc
{
  "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](https://nest.promptowl.ai/d/promptowl-documents/protocol/mcp-server) — the MCP protocol surface in depth
- [Authentication & API Keys](https://nest.promptowl.ai/d/promptowl-documents/protocol/authentication-api-keys) — `cnst_` keys and service tickets
- [Hosted Nest](https://nest.promptowl.ai/d/promptowl-documents/platform/hosted-nest/hosted-nest) — everything the hosted nest adds
- [REST API Reference](https://nest.promptowl.ai/d/promptowl-documents/protocol/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.