ContextStream MCP Server

What is ContextStream MCP Server about?

ContextStream MCP Server enables AI assistants to retain decisions, preferences, and lessons across sessions, and to query codebases with semantic search and graph analysis without requiring explicit tool names.

How to use ContextStream MCP Server?

Install – run npx -y @contextstream/mcp-server (or install globally with npm install -g @contextstream/mcp-server).
Configure – add a server entry to your MCP client (Cursor, VS Code, Claude, Codex, etc.) using the provided JSON/TOML examples. Set required environment variables such as CONTEXTSTREAM_API_URL and either CONTEXTSTREAM_API_KEY or CONTEXTSTREAM_JWT.
Start – execute the server with npx -y @contextstream/mcp-server (or contextstream-mcp if installed globally).
Interact – AI tools call functions like session_init, context_smart, session_capture, projects_ingest_local, graph_ingest, etc., to load context, search code, capture memories, and analyze dependencies.

Key Features of ContextStream MCP Server

Session‑aware context loading (session_init, context_smart).
Memory capture & recall for decisions, preferences, tasks, bugs, and lessons.
Multi‑mode code search: semantic, hybrid, keyword, pattern.
Knowledge‑graph generation with import, call, data‑flow, and type layers.
Graph ingestion (graph_ingest) and local project indexing (projects_ingest_local).
Auto‑context initialization on first tool call in a new session.
Configurable toolsets: light (~30 tools), standard (~50 tools, default), complete (~86 tools).
PRO tool gating with upgrade links for free‑plan users.

Use Cases of ContextStream MCP Server

AI‑augmented development – keep a persistent “brain” that remembers architectural decisions, tech stacks, and bug fixes across coding sessions.
Semantic code navigation – locate relevant code snippets (e.g., payment logic) without remembering exact filenames or symbols.
Impact analysis – query dependencies, call paths, or circular references before modifying a service.
Team knowledge sharing – store lessons learned or design rationales that new team members can retrieve via natural language.
Automated documentation – generate summaries of workspace context or project decisions on demand.

FAQ

Q: Do I need to write special commands for the AI tool? A: No. The AI simply describes the desired action (e.g., “show me the payment code”) and the server selects the appropriate tool.

Q: Which environment variables are mandatory? A: CONTEXTSTREAM_API_URL and either CONTEXTSTREAM_API_KEY or CONTEXTSTREAM_JWT.

Q: How do I limit the number of exposed tools? A: Set CONTEXTSTREAM_TOOLSET=light or light in the server env, or use CONTEXTSTREAM_TOOL_ALLOWLIST to specify exact tools.

Q: Can I write ingested files to disk for testing? A: Yes, by setting the server‑side QA_FILE_WRITE_ROOT and passing write_to_disk:true to projects_ingest_local.

Q: How are PRO tools handled for free users? A: Calls to PRO tools return an upgrade message with a configurable link (CONTEXTSTREAM_UPGRADE_URL).

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:

You say...	ContextStream does...
"session summary"	Gets a summary of your workspace context
"what did we decide about auth?"	Recalls past decisions about authentication
"remember we're using PostgreSQL"	Saves this to memory for future sessions
"search for payment code"	Searches your codebase semantically
"what depends on UserService?"	Analyzes code dependencies

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.

ContextStream in action

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)
Graph ingestion for full graph builds (graph_ingest)
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

Graph tiers

Pro (Graph-Lite): module-level import graph, dependencies, and 1-hop impact
Elite/Team (Full Graph): module + call + dataflow + type layers, plus graph_ingest

Requirements

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

Quickstart

Setup wizard (recommended)

This interactive wizard sets up authentication, installs editor rules, and writes MCP config files for the tools you select.

npx -y @contextstream/mcp-server setup

Notes:

Uses browser/device login by default and creates an API key for you.
Prompts for toolset selection: light (~30 tools), standard (default, ~50 tools), or complete (~86 tools including workspaces, projects, search, memory, graph, AI, and integrations).
To avoid re-auth prompts on subsequent runs, the wizard saves that API key to ~/.contextstream/credentials.json (and also writes it into the MCP config files it generates). Delete that file to force a fresh login.
Codex CLI MCP config is global-only (~/.codex/config.toml), so the wizard will always write Codex config globally when selected.
Some tools still require UI/CLI-based MCP setup (the wizard will tell you when it can't write a config).
Preview changes without writing files: npx -y @contextstream/mcp-server setup --dry-run

Run the server

Run directly (recommended for MCP configs):

npx -y @contextstream/mcp-server

Or install globally:

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

Keeping updated

To get the latest features and bug fixes, update periodically:

npm update -g @contextstream/mcp-server

The MCP server will warn you when a newer version is available. After updating, restart your AI tool to use the new version.

Configure your MCP client

Manual setup

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

If you prefer to configure things by hand (or your tool can't be auto-configured), add the ContextStream MCP server to your client using one of the examples below.

Toolset: By default, the server exposes the standard toolset (~50 tools). Use CONTEXTSTREAM_TOOLSET=light to reduce tool count (~30 tools), or CONTEXTSTREAM_TOOLSET=complete to expose all ~86 tools (workspaces, projects, search, memory, graph, AI, integrations). See the full tool catalog.

Cursor / Windsurf / Claude Desktop (JSON)

These clients use the mcpServers JSON schema:

Cursor: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)
Windsurf: ~/.codeium/windsurf/mcp_config.json
Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Many other MCP JSON clients also use this same mcpServers shape (including Claude Code project scope via .mcp.json).

Standard toolset (default, ~50 tools):

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

Complete toolset (~86 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_TOOLSET": "complete"
      }
    }
  }
}

VS Code (`.vscode/mcp.json`)

VS Code uses a different schema with a top-level servers map:

Core toolset (default):

{
  "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"
      }
    }
  }
}

Complete toolset (~86 tools):

{
  "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",
        "CONTEXTSTREAM_TOOLSET": "complete"
      }
    }
  }
}

Strong recommendation: VS Code supports inputs so you don’t have to hardcode secrets in a committed file:

{
  "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):

Standard toolset (default):

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

Complete toolset (~86 tools):

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

Note: Claude Code may warn about large tool contexts when using complete. The default is standard (~50 tools). Use light for fewer tools.

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

Alternative (JSON form):

Standard:

claude mcp add-json contextstream \
'{"type":"stdio","command":"npx","args":["-y","@contextstream/mcp-server"],"env":{"CONTEXTSTREAM_API_URL":"https://api.contextstream.io","CONTEXTSTREAM_API_KEY":"your_api_key"}}'

Complete:

claude mcp add-json contextstream \
'{"type":"stdio","command":"npx","args":["-y","@contextstream/mcp-server"],"env":{"CONTEXTSTREAM_API_URL":"https://api.contextstream.io","CONTEXTSTREAM_API_KEY":"your_api_key","CONTEXTSTREAM_TOOLSET":"complete"}}'

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

Standard toolset (default):

[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"

Complete toolset (~86 tools):

[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"
CONTEXTSTREAM_TOOLSET = "complete"

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

Variable	Required	Description
`CONTEXTSTREAM_API_URL`	Yes	Base API URL (e.g. `https://api.contextstream.io`)
`CONTEXTSTREAM_API_KEY`	Yes*	API key (*required unless `CONTEXTSTREAM_JWT` is set)
`CONTEXTSTREAM_JWT`	Yes*	JWT (*required unless `CONTEXTSTREAM_API_KEY` is set)
`CONTEXTSTREAM_WORKSPACE_ID`	No	Default workspace ID fallback
`CONTEXTSTREAM_PROJECT_ID`	No	Default project ID fallback
`CONTEXTSTREAM_USER_AGENT`	No	Custom user agent string
`CONTEXTSTREAM_TOOLSET`	No	Tool bundle to expose: `light` (~30 tools), `standard` (default, ~50 tools), or `complete` (~86 tools). Claude Code/Desktop may warn about large tool contexts with `complete`.
`CONTEXTSTREAM_TOOL_ALLOWLIST`	No	Comma-separated tool names to expose (overrides toolset)
`CONTEXTSTREAM_PRO_TOOLS`	No	Comma-separated tool names treated as PRO (default: `ai_context,ai_enhanced_context,ai_context_budget,ai_embeddings,ai_plan,ai_tasks`)
`CONTEXTSTREAM_UPGRADE_URL`	No	Upgrade link shown when Free users call PRO tools (default: `https://contextstream.io/pricing`)

Server-side environment variables (API)

The following environment variables are configured on the ContextStream API server (not in your MCP client config):

Variable	Required	Description
`QA_FILE_WRITE_ROOT`	No	Server-side root directory for `write_to_disk` file writes. When set, the API allows the `projects_ingest_local` tool to write ingested files to disk for testing/QA purposes. Files are written under `<QA_FILE_WRITE_ROOT>/<project_id>/<relative_path>`. If not set, `write_to_disk` requests are rejected.

File write parameters for `projects_ingest_local`

The projects_ingest_local tool accepts two optional parameters for QA/testing scenarios:

Parameter	Type	Default	Description
`write_to_disk`	boolean	`false`	When `true`, writes ingested files to disk on the API server under `QA_FILE_WRITE_ROOT` before indexing. Requires the API to have `QA_FILE_WRITE_ROOT` configured.
`overwrite`	boolean	`false`	When `true` (and `write_to_disk` is enabled), allows overwriting existing files. Otherwise, existing files are skipped.

Example usage:

{
  "path": "/path/to/local/project",
  "write_to_disk": true,
  "overwrite": false
}

Note: The write_to_disk feature is intended for testing, QA, and development scenarios where you need to materialize files on a test server. In production, QA_FILE_WRITE_ROOT should typically be unset to disable file writes.

Usage patterns

Recommended flow for AI tools

Start of a conversation: call session_init(folder_path="...", context_hint="<first user message>")
Before subsequent responses: call context_smart(user_message="<current user message>")
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

License

MIT

ContextStream MCP Server