MCP Configuration

The ContextKit MCP server can be configured for any MCP-compatible client. You can run it locally (stdio or self-hosted HTTP) or connect to the hosted endpoint at api.runcontext.dev/mcp.

Connection modes

Mode	Transport	Use case
Local stdio	stdin/stdout	Single-user, local development
Local HTTP	Streamable HTTP	Self-hosted, shared team server
Hosted	Streamable HTTP	Managed cloud, no server to run

For the hosted endpoint, replace {org} with your organization slug and set CONTEXTKIT_API_KEY to your API key (available from the ContextKit dashboard).

Claude Code

{
  "mcpServers": {
    "contextkit": {
      "command": "npx",
      "args": ["@runcontext/cli", "serve", "--stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}

{
  "mcpServers": {
    "contextkit": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

{
  "mcpServers": {
    "contextkit": {
      "url": "https://api.runcontext.dev/mcp/{org}",
      "headers": {
        "Authorization": "Bearer ${CONTEXTKIT_API_KEY}"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "contextkit": {
      "command": "npx",
      "args": ["@runcontext/cli", "serve", "--stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}

{
  "mcpServers": {
    "contextkit": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

{
  "mcpServers": {
    "contextkit": {
      "url": "https://api.runcontext.dev/mcp/{org}",
      "headers": {
        "Authorization": "Bearer ${CONTEXTKIT_API_KEY}"
      }
    }
  }
}

VS Code

VS Code supports MCP servers via its built-in chat/copilot agent framework. Configuration lives in .vscode/mcp.json.

{
  "mcpServers": {
    "contextkit": {
      "command": "npx",
      "args": ["@runcontext/cli", "serve", "--stdio"],
      "cwd": "${workspaceFolder}"
    }
  }
}

{
  "mcpServers": {
    "contextkit": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

{
  "mcpServers": {
    "contextkit": {
      "url": "https://api.runcontext.dev/mcp/{org}",
      "headers": {
        "Authorization": "Bearer ${CONTEXTKIT_API_KEY}"
      }
    }
  }
}

Windsurf

Windsurf reads MCP configuration from ~/.codeium/windsurf/mcp_config.json.

Local (stdio)
Hosted

{
  "mcpServers": {
    "contextkit": {
      "command": "npx",
      "args": ["@runcontext/cli", "serve", "--stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}

{
  "mcpServers": {
    "contextkit": {
      "serverUrl": "https://api.runcontext.dev/mcp/{org}",
      "headers": {
        "Authorization": "Bearer ${CONTEXTKIT_API_KEY}"
      }
    }
  }
}

OpenAI Codex

OpenAI Codex CLI reads MCP configuration from a mcp.json file or inline config.

Local (stdio)
Hosted

{
  "mcpServers": {
    "contextkit": {
      "command": "npx",
      "args": ["@runcontext/cli", "serve", "--stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}

{
  "mcpServers": {
    "contextkit": {
      "url": "https://api.runcontext.dev/mcp/{org}",
      "headers": {
        "Authorization": "Bearer ${CONTEXTKIT_API_KEY}"
      }
    }
  }
}

Generic MCP client

Any MCP-compatible client can connect using either transport.

Local (stdio)

Run the MCP server as a subprocess:

npx @runcontext/cli serve --stdio

The server communicates over stdin/stdout using the MCP JSON-RPC protocol.

Local (HTTP)

Start the server in HTTP mode:

npx @runcontext/cli serve --http --port 3000

Then point your client at:

http://localhost:3000/mcp

Hosted

Send MCP JSON-RPC requests to the hosted endpoint:

POST https://api.runcontext.dev/mcp/{org}
Authorization: Bearer <your-api-key>
Content-Type: application/json

The hosted endpoint uses Streamable HTTP transport. Example initialize request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

Verifying the connection

Once configured, your AI tool should discover the ContextKit resources and tools automatically. You can verify by asking the agent:

“What MCP resources are available?”

It should list the context:// resources. You can also test a tool call:

“Search my semantic layer for revenue metrics.”

The agent should call context_search and return results from your context directory.

CLI flags

The serve command accepts the following flags:

Flag	Description	Default
`--http`	Use HTTP transport (default is stdio)	Off
`--port <number>`	Port for HTTP server	`3000`
`--host <address>`	Host address to bind	`0.0.0.0`
`--context-dir <path>`	Path to context files	`./context`