Environment variables

The MCP server reads configuration from environment variables:

The HMAC secret is used by the V2 client for request signing. If none of the HMAC environment variables are set, V2-specific features like semantic search and the enrichment pipeline will not be available.

Claude Desktop configuration

Add the Contox MCP server to your Claude Desktop configuration file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "contox": {
      "command": "contox-mcp",
      "env": {
        "CONTOX_API_KEY": "<your-key>",
        "CONTOX_PROJECT_ID": "<project-id>",
        "CONTOX_TEAM_ID": "<team-id>",
        "CONTOX_HMAC_SECRET": "<hmac-secret>"
      }
    }
  }
}

After saving the configuration, restart Claude Desktop. You should see the Contox tools listed when you click the MCP tools icon in the chat input area.

Claude Code (.mcp.json)

For Claude Code, you can place a .mcp.json file in your project root:

{
  "mcpServers": {
    "contox": {
      "command": "contox-mcp",
      "env": {
        "CONTOX_API_KEY": "<your-key>",
        "CONTOX_PROJECT_ID": "<project-id>",
        "CONTOX_TEAM_ID": "<team-id>",
        "CONTOX_HMAC_SECRET": "<hmac-secret>"
      }
    }
  }
}

Claude Code will automatically detect and start the MCP server when it opens a project with this file.

Project auto-resolution

The MCP server can also resolve project configuration from a .contox.json file in the current working directory or a parent directory. This file is typically created by contox init from the CLI:

{
  "projectId": "<project-id>",
  "teamId": "<team-id>",
  "apiUrl": "https://contox.dev/api"
}

When .contox.json is present, you only need to provide CONTOX_API_KEY as an environment variable. The project ID, team ID, and API URL are read from the file automatically.

If both .contox.json and environment variables are set, the environment variables take precedence.

Getting your credentials

1. API Key — Go to Dashboard > API Keys and generate a new key
2. Project ID — Go to Dashboard > Projects and copy the project ID
3. Team ID — Found on your Dashboard > Settings page
4. HMAC Secret — Generated during project setup; visible in your project settings

Verifying the connection

Once configured, start a new Claude session and ask:

Load my project memory

Claude should call contox_get_memory and return your project brain document. If this works, the MCP server is correctly configured.

Troubleshooting

"Error loading memory" on first use

Make sure your API key, project ID, and team ID are all correct. Check that the project exists in your Contox dashboard.

Tools not appearing in Claude Desktop

Restart Claude Desktop after editing the configuration file. Check the Claude Desktop logs for MCP connection errors.

V2 features unavailable

If semantic search or the enrichment pipeline is not working, verify that CONTOX_HMAC_SECRET is set correctly. The HMAC secret must match the one configured for your project.