MCP Server

ctx mcp¶

Run ctx as a Model Context Protocol (MCP) server. MCP is a standard protocol that lets AI tools discover and consume context from external sources via JSON-RPC 2.0 over stdin/stdout.

This makes ctx accessible to any MCP-compatible AI tool without custom hooks or integrations:

• Claude Desktop
• Cursor
• Windsurf
• VS Code Copilot
• Any tool supporting MCP

ctx mcp serve¶

Start the MCP server. This command reads JSON-RPC 2.0 requests from stdin and writes responses to stdout. It is intended to be launched by MCP clients, not run directly.

ctx mcp serve

Flags: None. The server uses the configured context directory (from --context-dir, CTX_DIR, .ctxrc, or the default .context).

Configuration¶

Claude Desktop¶

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ctx": {
      "command": "ctx",
      "args": ["mcp", "serve"]
    }
  }
}

Cursor¶

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "ctx": {
      "command": "ctx",
      "args": ["mcp", "serve"]
    }
  }
}

VS Code (Copilot)¶

Add to .vscode/mcp.json:

{
  "servers": {
    "ctx": {
      "command": "ctx",
      "args": ["mcp", "serve"]
    }
  }
}

Resources¶

Resources expose context files as read-only content. Each resource has a URI, name, and returns Markdown text.

The agent resource assembles all non-empty context files into a single Markdown document, ordered by the configured read priority.

Resource Subscriptions¶

Clients can subscribe to resource changes via resources/subscribe. The server polls for file mtime changes (default: 5 seconds) and emits notifications/resources/updated when a subscribed file changes on disk.

Tools¶

Tools expose ctx commands as callable operations. Each tool accepts JSON arguments and returns text results.

ctx_status¶

Show context health: file count, token estimate, and per-file summary.

Arguments: None. Read-only.

ctx_add¶

Add a task, decision, learning, or convention to the context.

ctx_complete¶

Mark a task as done by number or text match.

ctx_drift¶

Detect stale or invalid context. Returns violations, warnings, and passed checks.

Arguments: None. Read-only.

ctx_recall¶

Query recent AI session history (summaries, decisions, topics).

Read-only.

ctx_watch_update¶

Apply a structured context update to .context/ files. Supports task, decision, learning, convention, and complete entry types. Human confirmation is required before calling.

ctx_compact¶

Move completed tasks to the archive section and remove empty sections from context files. Human confirmation required.

ctx_next¶

Suggest the next pending task based on priority and position.

Arguments: None. Read-only.

ctx_check_task_completion¶

Advisory check: after a write operation, detect if any pending tasks were silently completed. Returns nudge text if a match is found.

Read-only.

ctx_session_event¶

Signal a session lifecycle event. Type end triggers the session-end persistence ceremony - human confirmation required.

ctx_remind¶

List pending session-scoped reminders.

Arguments: None. Read-only.

Prompts¶

Prompts provide pre-built templates for common workflows. Clients can list available prompts via prompts/list and retrieve a specific prompt via prompts/get.

ctx-session-start¶

Load full context at the beginning of a session. Returns all context files assembled in priority read order with session orientation instructions.

ctx-add-decision¶

Format an architectural decision entry with all required fields.

ctx-add-learning¶

Format a learning entry with all required fields.

ctx-reflect¶

Guide end-of-session reflection. Returns a structured review prompt covering progress assessment and context update recommendations.

ctx-checkpoint¶

Report session statistics: tool calls made, entries added, and pending updates queued during the current session.