MCP Setup

The Contextia MCP server runs as a local subprocess launched by your AI coding client. Configuration is a one-time setup per machine — the server automatically discovers the correct project based on the working directory.

Prerequisites

Before configuring the MCP server, ensure you have:

1. Python 3.12 or later installed and available on your PATH.
2. uv installed (the Python package manager). Install it with:

   curl -LsSf https://astral.sh/uv/install.sh | sh

3. A Contextia project. The server needs a .contextia/ directory to serve. If you do not have one yet:

   uvx contextia init

Tip

You do not need to install Contextia globally. The uvx command downloads and runs the package in an isolated environment on the fly. It caches the installation after the first run, so subsequent launches are fast.

Claude Code

Claude Code supports MCP servers natively. Add Contextia with a single command:

claude mcp add contextia -- uvx contextia-mcp

This registers the server globally in your Claude Code configuration. It will be available in every project directory that contains a .contextia/ folder.

To verify the server is registered:

claude mcp list

You should see contextia in the output with its command (uvx contextia-mcp).

To remove the server:

claude mcp remove contextia

How Claude Code launches the server

When you open a conversation in Claude Code, it starts the MCP server as a child process with the current working directory set to your project root. The server inherits this directory and uses it to locate .contextia/config.yaml. No additional path configuration is needed.

Cursor

Cursor reads MCP server configuration from .cursor/mcp.json in your project root. Create this file if it does not exist:

{
  "mcpServers": {
    "contextia": {
      "command": "uvx",
      "args": ["contextia-mcp"]
    }
  }
}

After saving the file, restart Cursor or reload the window for the server to be picked up.

Note

The .cursor/mcp.json file is project-specific. If you work on multiple Contextia projects, each one needs its own copy. You may want to add this file to your .gitignore or commit it as part of the project setup — the choice depends on whether your team uses Cursor.

Cursor with a specific Python version

If you need to pin a Python version (e.g., your system default is 3.11 but Contextia requires 3.12), specify the full path to uvx:

{
  "mcpServers": {
    "contextia": {
      "command": "/usr/local/bin/uvx",
      "args": ["contextia-mcp"],
      "env": {
        "UV_PYTHON": "3.12"
      }
    }
  }
}

VS Code

VS Code supports MCP servers through the .vscode/mcp.json configuration file:

{
  "servers": {
    "contextia": {
      "type": "stdio",
      "command": "uvx",
      "args": ["contextia-mcp"]
    }
  }
}

Place this file in the .vscode/ directory at your project root. VS Code picks up the configuration automatically when the directory is opened.

Caution

VS Code MCP support requires the appropriate extension (such as the GitHub Copilot extension with MCP support, or another MCP-compatible extension). Check your extension documentation for the exact configuration format, as it may vary slightly between extensions.

Verifying the server works

After configuring your client, verify the server is functional by asking your AI agent a simple question that triggers a Contextia tool call. For example:

“List all specs in this project.”

The agent should call mcp_list(type="spec") and return results from your .contextia/system/specs/ directory.

You can also test the server manually from the command line:

cd /path/to/your/project
uvx contextia-mcp

The server starts and waits for JSON-RPC messages on stdin. You will not see any output — this is expected. The server communicates via structured messages, not human-readable text. Press Ctrl+C to stop it.

Debug mode

For troubleshooting, you can run the MCP server with verbose logging enabled:

uvx contextia-mcp --debug

In debug mode, the server writes diagnostic information to stderr, including:

• The resolved project root path.
• Each tool call received, with its parameters.
• Each response sent, with its size in bytes.
• Any errors encountered during execution.

Since MCP clients typically capture stderr, check your client’s log output to see these messages. In Claude Code:

claude mcp logs contextia

Troubleshooting

Server not starting

Symptom: The AI agent cannot access Contextia tools. Tool calls fail or the agent does not list Contextia tools at all.

Check the following:

1. Is uvx on your PATH? Run which uvx in your terminal. If not found, install uv.
2. Is the command correct? The package name is contextia-mcp (with a hyphen), not contextia_mcp or contextia mcp.
3. Can you run it manually? Try uvx contextia-mcp from your project directory. If it fails, the error message will indicate the problem.
4. Python version. Contextia requires Python 3.12+. Check with python3 --version. If your default Python is older, set UV_PYTHON=3.12 in the environment.

Project not found

Symptom: Tools return a message like “No Contextia project found. Run contextia init to create one.”

This means the server is running but cannot find .contextia/config.yaml. Check:

1. Working directory. The server inherits its working directory from the client. Make sure your editor or terminal is opened at the project root (or a subdirectory of it).
2. Config file exists. Verify that .contextia/config.yaml exists in your project:

   ls -la .contextia/config.yaml

3. Permissions. The server process needs read access to the .contextia/ directory and all files within it.

Tools returning empty results

Symptom: Tools like mcp_search or mcp_list return no results even though you have specs and tasks.

Possible causes:

1. Frontmatter errors. If a spec file has invalid YAML frontmatter, it will be skipped during indexing. Run contextia check from the CLI to identify malformed files.
2. Wrong type filter. Ensure you are querying the correct artifact type. Specs are in system/specs/, tasks in work/tasks/, decisions in system/rationale/.
3. Cache stale. Delete .contextia/.cache/ and retry. The cache is fully rebuildable.

Client-specific issues

Claude Code: If claude mcp list does not show contextia, try re-adding it. If tool calls time out, check that uvx can download the package (network access required on first run).

Cursor: After editing .cursor/mcp.json, you must reload the Cursor window (Cmd+Shift+P > “Developer: Reload Window”). Cursor does not hot-reload MCP configuration.

VS Code: Ensure the MCP extension you are using is active and configured to read from .vscode/mcp.json. Some extensions use different configuration paths.

Getting help

If the troubleshooting steps above do not resolve your issue:

1. Run uvx contextia-mcp --debug manually and examine the stderr output.
2. Check the Contextia GitHub issues for known problems.
3. File a new issue with the debug output, your client name and version, and your Python and uv versions.