Package Exports

@contextstream/mcp-server
@contextstream/mcp-server/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@contextstream/mcp-server) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

License

MIT