MCP Server

The ContextNest (Community) server exposes vault operations as MCP tools that any MCP-compatible AI client can call. Every tool is named context_* (with a handful of server-level nest_* tools on the cross-nest endpoint). Tool list verified against Community/src/mcp/tools.ts.

Endpoints

The server offers two MCP surfaces:

• Per-nest — POST/GET/DELETE <base>/nests/<nest-id>/mcp — the full toolset, including writes. Scoped to a single nest.
• Server-level (cross-nest) — ALL <base>/mcp — one stateless connection for everything readable across the nests you can see, plus a small set of safe writes. Carries nest_index and read tools; the only writes are nest_create and context_create (creating into a brand-new nest, where there is no cross-nest authz to get wrong).

Configuration

Point your MCP client at the endpoint (streamable HTTP). For a local stdio-style setup:

{
  "mcpServers": {
    "contextnest": {
      "command": "contextnest-mcp-server",
      "args": ["--vault", "/path/to/your/vault"]
    }
  }
}

Always-on tools

These context_* tools are registered on every per-nest connection (from TOOL_DEFINITIONS in tools.ts).

Retrieval & read

Authoring

Governance & review

Sharing & sync

Note: context_delete and context_move are present in tools.ts and registered on the per-nest surface, in addition to the tools listed in the update brief.

Server-level (/mcp) toolset

The cross-nest endpoint advertises a reduced set: nest_index, nest_create, context_query, context_search, context_get, context_list, context_overview, context_resolve, and context_create. Reads span the nests you can see; the only writes are nest_create and context_create (into a new nest).

Workflow-plane tools (workflow_*)

A second family of tools — workflow_run, workflow_run_step, workflow_run_close, workflow_run_get, workflow_runs_list, workflow_edges_list, workflow_edge_create, workflow_edge_delete, workflow_edge_types_list, workflow_edge_type_upsert, workflow_edge_type_delete — is advertised only when FEATURE_WORKFLOW_PLANE is enabled. The flag is read per request (the server is rebuilt per call), so toggling it at runtime takes effect immediately. When off, these tools do not appear in the tool list at all.

Deprecated legacy aliases

Earlier releases exposed a different tool vocabulary (e.g. read_document, list_documents, search, create_document, update_document, delete_document, publish_document, vault_info, resolve, get_history, …). These older names are retained as deprecated aliases that map onto the canonical context_* catalog above, so existing clients keep working. New integrations should use the context_* names.

Error handling

Tool results carry structured error signaling, not just prose. A denial / not-found / failure sets isError: true on the MCP CallToolResult and attaches a machine-readable { code, message } in structuredContent — codes are the engine's ERROR_CODES (DOCUMENT_NOT_FOUND, DOCUMENT_ALREADY_EXISTS, UNAUTHORIZED_ACTION, VERSION_NOT_FOUND, INTERNAL). Chat clients keep reading the unchanged prose content; machine callers (such as ctx driving the server over MCP) read the structured half and map it back to a typed engine error instead of string-matching a sentence. The read/query/create/update/delete/versions and context_submit_review tools also return their catalog JSON payload as structuredContent alongside the prose.

How it works

The server wraps the same engine used by the CLI, reading from and writing to nests on disk (or a hosted store), so any MCP client — Claude, Cursor, VS Code with Copilot, and others — can operate on your knowledge through the tools above. Under stewardship, writes and reads respect approval state: unapproved drafts are gated from AI queries until a steward approves them.