ContextStream MCP Server

Persistent memory, semantic search, and code intelligence for any MCP-compatible AI tool.

ContextStream is a shared "brain" for your AI workflows. It stores decisions, preferences, and lessons, and lets your AI tools search and analyze your codebase with consistent context across sessions.

Just Ask

You don't need to memorize tool names. Just describe what you want and your AI uses the right ContextStream tools automatically:

No special syntax. No commands to learn. Just ask.

Tip: For best results, add the recommended editor rules so your AI consistently calls session_init / context_smart automatically.

Features

• Session-aware context loading (session_init, context_smart)
• Memory capture and recall (decisions, preferences, tasks, bugs, lessons)
• Code search (semantic, hybrid, keyword, pattern)
• Knowledge graph and code analysis (dependencies, impact, call paths, circular deps, unused code)
• Local repo ingestion for indexing (projects_ingest_local)
• Auto-context: on the first tool call in a new session, the server can auto-initialize context

Requirements

• Node.js 18+
• A ContextStream account and either an API key or a JWT

Quickstart

Run directly (recommended for MCP configs):

npx -y @contextstream/mcp-server

Or install globally:

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

Configure your MCP client

Cursor / VS Code / Windsurf / Claude Desktop (JSON)

Add to your MCP config:

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

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"

After editing, restart your MCP client so it reloads the server configuration.

Authentication

You can authenticate using either:

• CONTEXTSTREAM_API_KEY (recommended for local/dev)
• CONTEXTSTREAM_JWT (useful for hosted or user-session flows)

Environment variables

Usage patterns

Recommended flow for AI tools

1. Start of a conversation: call session_init(folder_path="...", context_hint="<first user message>")
2. Before subsequent responses: call context_smart(user_message="<current user message>")
3. After important outcomes: call session_capture(...) or session_capture_lesson(...)

Omit workspace/project IDs (recommended)

Most tools accept omitted workspace_id / project_id and will use the current session defaults.

• If you see “workspace_id is required”, call session_init first (or pass the ID explicitly).
• If you regularly work in the same repo, use workspace_associate once so the server can auto-select the right workspace for that folder.

First-time setup (no workspaces yet)

If your account has no workspaces, ContextStream will prompt your AI assistant to ask you for a workspace name.

• Provide a workspace name (e.g., your company/team/product)
• The current folder is created as a project inside that workspace
• Recommended: call workspace_bootstrap(workspace_name="...", folder_path="...")

Free vs PRO tools

Tools are labeled as (Free) or (PRO) in the MCP tool list.

• Default PRO tools: ai_context, ai_enhanced_context, ai_context_budget, ai_embeddings, ai_plan, ai_tasks
• If a Free-plan user calls a PRO tool, the server returns an upgrade message with a link.
• Override the PRO list via CONTEXTSTREAM_PRO_TOOLS and the upgrade link via CONTEXTSTREAM_UPGRADE_URL.

Troubleshooting

• Tools not appearing: restart the client after editing MCP config; confirm Node 18+ is available to the client runtime.
• Unauthorized errors: verify CONTEXTSTREAM_API_URL and CONTEXTSTREAM_API_KEY (or CONTEXTSTREAM_JWT).
• Wrong workspace/project: use workspace_associate to map the current repo folder to the correct workspace.

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

• Website: https://contextstream.io
• Docs: https://contextstream.io/docs/mcp
• Pricing: https://contextstream.io/pricing
• npm: https://www.npmjs.com/package/@contextstream/mcp-server
• GitHub: https://github.com/contextstream/mcp-server

License

MIT