Claude Code & Claude Desktop

Claude integrates with Contox through the Model Context Protocol (MCP), giving it native access to 23 tools for loading, searching, saving, and managing project memory. This is the deepest integration available.

What you get

With MCP, Claude can:

• Load the full project brain at session start (contox_get_memory)
• Search memory semantically (contox_search)
• Build focused context packs for specific tasks (contox_context_pack)
• Save structured session work when you ask (contox_save_session)
• Scan your codebase (contox_scan)
• Digest git history (contox_git_digest)
• Manage contexts, links, entries, and the knowledge graph
• Run memory hygiene analysis (contox_hygiene)

All 23 tools are documented in the MCP Server Reference.

Prerequisites

• Node.js 18+ installed
• Contox MCP server installed: npm install -g @contox/mcp-server
• A Contox account with an API key and a project

Setup for Claude Code (.mcp.json)

Claude Code reads MCP server configuration from a .mcp.json file in your project root.

Create .mcp.json in your workspace:

{
  "mcpServers": {
    "contox": {
      "command": "contox-mcp",
      "env": {
        "CONTOX_API_KEY": "your-api-key",
        "CONTOX_API_URL": "https://contox.dev",
        "CONTOX_TEAM_ID": "your-team-id",
        "CONTOX_PROJECT_ID": "your-project-id"
      }
    }
  }
}

Replace the placeholder values with your actual credentials from the Contox dashboard.

Setup for Claude Desktop

Claude Desktop uses a global configuration file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Contox server to your configuration:

{
  "mcpServers": {
    "contox": {
      "command": "contox-mcp",
      "env": {
        "CONTOX_API_KEY": "your-api-key",
        "CONTOX_API_URL": "https://contox.dev",
        "CONTOX_TEAM_ID": "your-team-id",
        "CONTOX_PROJECT_ID": "your-project-id"
      }
    }
  }
}

Restart Claude Desktop after saving the configuration. The Contox tools will appear in the tools list.

Automatic setup via VS Code extension

The easiest way to configure Claude is through the VS Code extension setup wizard:

1. Run Contox: Setup Wizard from the command palette
2. Complete the login, team, and project steps
3. In Step 4, check Claude (checked by default)
4. The extension creates .mcp.json with your credentials pre-filled

The extension also stores the HMAC secret for auto-capture signing.

CLAUDE.md injection

In addition to the MCP server, Contox injects a memory summary into your CLAUDE.md file between markers:

<!-- contox:start -->
# Contox — Auto-generated Project Context
...memory summary here...
<!-- contox:end -->

Your own content outside the markers is preserved. This gives Claude Code additional context even before MCP tools are invoked.

How a session works

1. Session starts -- Claude calls contox_get_memory to load the full project brain
2. During work -- Claude uses tools as needed: contox_search to find relevant memory, contox_context_pack for focused context, contox_scan for codebase analysis
3. Session end -- When you say "save", Claude calls contox_save_session with a structured summary

Environment variables

The MCP server accepts these environment variables:

Verifying the connection

After setup, start a new Claude session and ask it to load project memory. You should see Claude invoke the contox_get_memory tool and return your project's brain document.

Next steps

• MCP Server Overview -- Full reference for all 23 tools
• Cursor Integration -- Add file-based integration alongside MCP