ContextStream MCP Server

Persistent memory, semantic search, and code intelligence for any MCP-compatible AI tool (Cursor, Claude Code, Windsurf, VS Code, Claude Desktop, Codex CLI, etc.).

ContextStream is a shared "brain" for AI-assisted development. It stores decisions, preferences, lessons, tasks, and project context — and lets your AI tools search and analyze your codebase with consistent context across sessions.

v0.4.x: Consolidated domain tools (11 tools) for **75% lower tool-registry token overhead** vs previous versions.

Just Ask

You don't need to memorize tool names. Describe what you want and your AI will call the right ContextStream tools:

Tip: For best results, add the recommended editor rules so your AI reliably calls session_init / context_smart when appropriate: https://contextstream.io/docs/quickstart

Choose Your Mode (Token Footprint)

MCP clients often inject the tool catalog into the model context. v0.4.x is designed to keep that overhead small.

Note: The env var name for Router mode is CONTEXTSTREAM_PROGRESSIVE_MODE (historical naming). It enables the ~2-tool "router" surface.

Features

• Consolidated domain tools (v0.4.x): short tool list with action/mode dispatch
• Session-aware context loading (session_init, context_smart)
• Memory capture + recall (decisions, preferences, lessons, tasks, bugs)
• Code search (semantic, hybrid, keyword, pattern)
• Knowledge graph + code analysis (dependencies, impact, call paths, circular deps, unused code)
• Graph ingestion for full graph builds (graph(action="ingest"))
• Local repo ingestion for indexing (project(action="ingest_local"))
• Auto-context: on first tool call in a new session, the server can auto-initialize context

Graph Tiers

Requirements

• Node.js 18+
• A ContextStream account
• Auth via API key or JWT

Default API URL: https://api.contextstream.io

Quickstart (2 minutes)

1) Run the Setup Wizard (recommended)

The wizard:

• Authenticates (browser/device login by default)
• Creates/stores an API key
• Installs recommended editor rules (optional)
• Writes MCP config files for supported tools

npx -y @contextstream/mcp-server setup

Useful flags:

Notes:

• The wizard stores credentials at ~/.contextstream/credentials.json for convenience. Delete it to force a fresh login.
• Codex CLI MCP config is global-only (~/.codex/config.toml), so the wizard writes Codex config globally when selected.
• Some tools still require UI/CLI setup (the wizard will tell you when it can't write a config).

2) Run the MCP Server

Recommended (works well with MCP configs):

npx -y @contextstream/mcp-server

Or install globally:

npm install -g @contextstream/mcp-server
contextstream-mcp

3) Keeping Updated

If you use npx: Restart your AI tool/editor and run ContextStream again (or pin the version: npx -y @contextstream/mcp-server@0.4.3)

If you installed globally:

npm update -g @contextstream/mcp-server

After updating, restart your AI tool/editor so it reloads the tool catalog.

Configure Your MCP Client (Manual)

If you ran the setup wizard, you can usually skip this.

Cursor / Windsurf / Claude Desktop (JSON)

These clients use an mcpServers JSON config:

Consolidated (default):

{
  "mcpServers": {
    "contextstream": {
      "command": "npx",
      "args": ["-y", "@contextstream/mcp-server"],
      "env": {
        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
        "CONTEXTSTREAM_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Router mode (~2 meta-tools):

{
  "mcpServers": {
    "contextstream": {
      "command": "npx",
      "args": ["-y", "@contextstream/mcp-server"],
      "env": {
        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
        "CONTEXTSTREAM_API_KEY": "YOUR_API_KEY",
        "CONTEXTSTREAM_PROGRESSIVE_MODE": "true"
      }
    }
  }
}

VS Code (.vscode/mcp.json)

VS Code uses a top-level servers map:

{
  "servers": {
    "contextstream": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@contextstream/mcp-server"],
      "env": {
        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
        "CONTEXTSTREAM_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Strong recommendation: Use inputs so you don't commit secrets:

{
  "servers": {
    "contextstream": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@contextstream/mcp-server"],
      "env": {
        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
        "CONTEXTSTREAM_API_KEY": "${input:contextstreamApiKey}"
      }
    }
  },
  "inputs": [
    {
      "id": "contextstreamApiKey",
      "type": "promptString",
      "description": "ContextStream API Key",
      "password": true
    }
  ]
}

Claude Code (CLI)

User scope (all projects):

claude mcp add --transport stdio contextstream --scope user \
  --env CONTEXTSTREAM_API_URL=https://api.contextstream.io \
  --env CONTEXTSTREAM_API_KEY=YOUR_KEY \
  -- npx -y @contextstream/mcp-server

Router mode:

claude mcp add --transport stdio contextstream --scope user \
  --env CONTEXTSTREAM_API_URL=https://api.contextstream.io \
  --env CONTEXTSTREAM_API_KEY=YOUR_KEY \
  --env CONTEXTSTREAM_PROGRESSIVE_MODE=true \
  -- npx -y @contextstream/mcp-server

Windows caveat (native Windows, not WSL): if npx isn't found, use cmd /c npx -y @contextstream/mcp-server after --.

Codex CLI (~/.codex/config.toml)

[mcp_servers.contextstream]
command = "npx"
args = ["-y", "@contextstream/mcp-server"]

[mcp_servers.contextstream.env]
CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
CONTEXTSTREAM_API_KEY = "YOUR_API_KEY"

Tool Overview (v0.4.x Consolidated)

In consolidated mode, you call domain tools with action / mode:

Core

Domain Tools

Examples

search(mode="semantic", query="auth middleware")
memory(action="create_node", node_type="decision", title="Auth strategy", content="...")
graph(action="impact", target="UserService")

Full tool catalog: https://contextstream.io/docs/mcp/tools

Authentication

Set one of:

Environment Variables

Required

Token + Tool Surface Controls

Optional Defaults

Migration Notes (pre-0.4.x → 0.4.x)

Most workflows just work, but tool names change in consolidated mode.

If you rely on granular tool names, you can temporarily set:

CONTEXTSTREAM_CONSOLIDATED=false

Troubleshooting

Development

git clone https://github.com/contextstream/mcp-server.git
cd mcp-server
npm install
npm run dev
npm run typecheck
npm run build

Links

License

MIT