@contextstream/mcp-server

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.

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

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_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)

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="...")

Slash commands (prompts)

Most MCP clients expose ContextStream prompts as /contextstream:... slash commands.

• Prompts are parameter-free: selecting a command should immediately insert the template.
• Templates avoid asking for workspace/project IDs and instead rely on session_init + session defaults.

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

• Prompts/tools not appearing: restart the client after editing MCP config; confirm Node 18+ is available to the client runtime.
• Slash commands do nothing: update to the latest @contextstream/mcp-server and restart your MCP client (prompts are parameter-free and should insert immediately).
• 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