MCP Integration

Connect Your AI Tools

ContextStream integrates with AI tools via the Model Context Protocol (MCP). Give Codex CLI, Claude, Cursor, Windsurf, Cline, Kilo Code, and Roo Code persistent memory across all your conversations.

Setup Wizard (recommended)

Run one command to authenticate (browser/device login), create an API key, generate rules, and write the correct MCP config for your tool (including VS Code’s servers schema).

Terminal

npx -y @contextstream/mcp-server setup

What it does: writes MCP config (VS Code servers, Cursor/Windsurf/etc mcpServers), generates rules (Standard/Extended), and can link projects to a workspace.

Preview changes without writing files: npx -y @contextstream/mcp-server setup --dry-run

Manual configuration

Use the correct format per client (VS Code uses servers; many other clients use mcpServers).

Jump to your tool:

Cursor / VS CodeCodex CLIClaude CodeClaude DesktopWindsurfClineKilo CodeRoo Code

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external tools and data sources. With ContextStream's MCP server, your AI tools can:

• Remember conversations and decisions across sessions
• Search your codebase and documentation semantically
• Build and query knowledge graphs
• Share context between different AI tools

Just Use Natural Language

You don't need to memorize tool names or call them directly. Just describe what you want in plain English and your AI assistant will use the right tools automatically.

Just ask naturally:

• • "session summary"
• • "what did we decide about auth?"
• • "remember we're using PostgreSQL"
• • "search for payment code"

The AI handles the rest:

• • Finds relevant context automatically
• • Recalls past decisions when needed
• • Saves important information to memory
• • Searches code and documentation

Example: User types "session summary" in natural language

The AI understands your intent and calls the appropriate ContextStream tools behind the scenes.

Prerequisites

• A ContextStream account (the setup wizard can create an API key via browser login)
• Node.js 18+ installed on your system

Optional: Add GitHub + Slack context

Coming Soon

MCP gives your AI persistent memory. Connecting external sources (like GitHub and Slack) makes that memory much richer—so your AI can reference PRs, issues, and the discussions behind decisions.

These integrations are actively being developed. Check back soon or contact us to express interest.

Coming Soon

GitHub

Install the GitHub App, select repos, and sync issues/PRs/releases into memory.

Coming Soon

Slack

Connect Slack, choose channels, invite the bot, and sync conversations into memory.

Example prompts after you connect integrations:

• • "Search our Slack messages for the decision about rate limiting."
• • "What did we decide in GitHub issues about the auth flow?"
• • "Pull relevant context from GitHub PRs related to onboarding."

Cursor / VS Code

Cursor and VS Code use different MCP config schemas:

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

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

.vscode/mcp.json (VS Code native MCP)

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

Recommended: VS Code inputs (avoid committing API keys)

.vscode/mcp.json (with inputs)

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

After editing the config, restart your editor for changes to take effect.

Codex CLI

To use ContextStream with the Codex CLI, add the MCP server configuration to your ~/.codex/config.toml file:

~/.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 the config, restart Codex so it can load the ContextStream MCP server.

Claude Code (CLI)

Add ContextStream to Claude Code by running this command from your project directory:

Terminal

claude mcp add --transport stdio contextstream --env CONTEXTSTREAM_API_URL=https://api.contextstream.io --env CONTEXTSTREAM_API_KEY=your_api_key -- 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 --.

Alternative: add-json (stdio)

Terminal

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

Tip: for team setups, prefer a committed .mcp.json file (project scope) instead of embedding keys in shell history.

This adds ContextStream to ~/.claude.json under your project's path, making it available when working in that directory.

MCP Scope Options:

• • Local (default): Private to you, current project only → stored in ~/.claude.json under project path
• • User (--scope user): Private to you, all projects → stored in ~/.claude.json globally
• • Project (--scope project): Shared with team → stored in .mcp.json in project root (commit to git)

For team sharing, use project scope to create a .mcp.json file that can be committed to git:

.mcp.json (project scope)

After adding the MCP server, restart Claude Code for changes to take effect. Verify the server is loaded with claude mcp list. For project-scoped servers from .mcp.json, Claude Code will prompt for approval on first use.

Claude Desktop (GUI App)

Add ContextStream to the Claude Desktop application:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json

After editing the config, quit and restart Claude Desktop for changes to take effect.

Windsurf (Codeium)

Windsurf supports MCP servers through its configuration:

~/.codeium/windsurf/mcp_config.json

Cline

Add ContextStream to your Cline MCP configuration. Click the MCP Servers icon in Cline, select the "Configure" tab, then click "Configure MCP Servers" to edit:

cline_mcp_settings.json

After editing the config, restart Cline for changes to take effect. You can also use alwaysAllow to auto-approve specific tools.

Kilo Code

Add ContextStream to your Kilo Code MCP configuration. You can configure MCP servers globally or per-project:

Global: Click Settings → MCP Servers → Installed → Edit Global MCP to open mcp_settings.json

Project: .kilocode/mcp.json in your project root

.kilocode/mcp.json (or mcp_settings.json)

Project-level configs take precedence over global configs. Restart Kilo Code after editing.

Roo Code

Add ContextStream to your Roo Code MCP configuration. You can configure MCP servers globally or per-project:

Global: Click the settings icon → Edit Global MCP to open mcp_settings.json

Project: .roo/mcp.json in your project root

.roo/mcp.json (or mcp_settings.json)

Project-level configs take precedence over global configs. Restart Roo Code after editing.

Improve Automatic ContextStream Usage

Recommended

ContextStream's auto-context feature loads workspace context automatically when you use any ContextStream tool. However, AI assistants may not always proactively save decisions or recall past context. Adding editor AI rules improves consistency and ensures the AI automatically captures decisions, preferences, and important context throughout your conversations.

Critical: MCP Tool Naming Conventions

Different AI tools use different naming conventions for MCP tools. Using the wrong format will cause tools to not be found.

AI Tool	Tool Name Format	Example
Claude Code	mcp____	mcp__contextstream__session_init
Codex CLI	(raw name)	session_init
Cursor / Windsurf / Cline	(raw name)	session_init
Kilo Code / Roo Code	(raw name)	session_init

Summary: Only Claude Code uses the mcp__contextstream__ prefix. All other tools use raw tool names.

You can add ContextStream rules at two levels: Global (applies to all projects) or Project (applies to one project).

Global Rules (All Projects)

Add these once and they'll apply to every project automatically:

Editor	Global Rules Location
Windsurf	~/.codeium/windsurf/memories/global_rules.md
Cursor	Settings → General → Rules for AI
Cline	~/Documents/Cline/Rules/ folder
Kilo Code	~/.kilocode/rules/ folder
Roo Code	~/.roo/rules/ folder
Claude Code	~/.claude/CLAUDE.md
Codex CLI	~/.codex/AGENTS.md (global) or parent folder (e.g. ~/dev/AGENTS.md)

Project Rules (Single Project)

Add these to a specific project. For Windsurf and Cursor folder-based rules, set the activation mode to "Always On" so the rules are always active.

Editor	Project Rules Location
Windsurf	.windsurfrules or .windsurf/rules/*.md
Cursor	.cursorrules or .cursor/rules/*.mdc
Cline	.clinerules file or .clinerules/ folder
Kilo Code	.kilocode/rules/ folder
Roo Code	.roorules file or .roo/rules/ folder
Claude Code	CLAUDE.md in project root
Codex CLI	AGENTS.md in project root
Aider	.aider.conf.yml in project root

Activation Modes (Windsurf, Cursor, Kilo Code & Roo Code)

When using folder-based rules (e.g., .windsurf/rules/), each rule file has an activation mode:

• Always On — Always active (recommended for ContextStream)
• Manual — Only when you @mention the rule
• Model Decision — AI decides based on description
• Glob — Active for matching file patterns

Global rules (global_rules.md) and root-level files (.windsurfrules) are always active.

Prefer the setup wizard? Run it first. Otherwise, add these minimal rules manually. Examples for each editor:

Claude Code

For Claude Code, create a CLAUDE.md file in your project root or add to your global ~/.claude/CLAUDE.md:

CLAUDE.md (Minimal)

## ContextStream (Minimal)

- First user message: mcp__contextstream__session_init(folder_path="<cwd>", context_hint="<user_message>"), then answer.
- Every user message: mcp__contextstream__context_smart(user_message="<user_message>", format="minified", max_tokens=400) BEFORE answering.
  - Use max_tokens=200 for trivial/local edits, max_tokens=800 for deep debugging/architecture.
- If prior context is missing or user asks past decisions: mcp__contextstream__session_recall(query="<question>"), then answer.
- After meaningful work/decisions/preferences: mcp__contextstream__session_capture(event_type=decision|preference|task|insight, title="…", content="…").
- On frustration/corrections/tool mistakes: mcp__contextstream__session_capture_lesson(...).

Show full rules (verbose)

CLAUDE.md (Full)

## ContextStream Integration

You have access to ContextStream MCP tools for persistent memory and context.

## TL;DR - REQUIRED EVERY MESSAGE

| Message | What to Call |
|---------|--------------|
| **1st message** | `mcp__contextstream__session_init(folder_path="...", context_hint="<user's message>")` |
| **2nd+ messages** | `mcp__contextstream__context_smart(user_message="<user's message>")` |
| **After completing task** | `mcp__contextstream__session_capture(...)` - MUST capture decisions/insights |
| **User frustration/correction** | `mcp__contextstream__session_capture_lesson(...)` - MUST capture lessons |

**NO EXCEPTIONS.** Do not skip even if you think you have enough context.

---

### Why context_smart is Required (Even After session_init)

**Common mistake:** "session_init already gave me context, I don't need context_smart"

**This is WRONG. Here's why:**
- `session_init` returns the last ~10 items **BY TIME** (chronological)
- `context_smart` **SEARCHES** for items **RELEVANT to THIS message** (semantic)

**Example failure:**
- User asks: "how should I implement authentication?"
- Auth decisions were made 20 conversations ago
- `session_init` won't have it (too old, not in recent 10)
- `context_smart` FINDS it via semantic search

**Without context_smart, you WILL miss relevant older context.**

---

### When to Capture (MANDATORY)

| When | Tool | Example |
|------|------|---------|
| User makes a decision | `mcp__contextstream__session_capture` | "Let's use PostgreSQL" → capture as decision |
| User states preference | `mcp__contextstream__session_capture` | "I prefer TypeScript" → capture as preference |
| You complete a task | `mcp__contextstream__session_capture` | Capture what was done, decisions made |
| Need past context | `mcp__contextstream__session_recall` | "What did we decide about X?" |

**You MUST capture after completing any significant task.** This ensures future sessions have context.

---

### Behavior Rules

**First message of conversation:**
1. Call `mcp__contextstream__session_init(folder_path="<cwd>", context_hint="<user's message>")`
2. Then respond

**Every subsequent message:**
1. Call `mcp__contextstream__context_smart(user_message="<user's message>")` FIRST
2. Then respond

**After completing a task:**
1. Call `mcp__contextstream__session_capture` to save decisions, preferences, or insights
2. This is NOT optional

**When user asks about past decisions:**
- Use `mcp__contextstream__session_recall` - do NOT ask user to repeat themselves

---

### Lesson Capture (MANDATORY)

When the user:
1. **Expresses frustration** (caps, profanity, "COME ON", "WTF", repeated corrections)
2. **Corrects you** ("No, you should...", "That's wrong", "Fix this")
3. **Points out a mistake** (broken code, wrong approach, production issue)

You MUST immediately call `mcp__contextstream__session_capture_lesson` with:

| Field | Description | Example |
|-------|-------------|---------|
| `title` | What to remember | "Verify assets in git before pushing" |
| `severity` | `critical`/`high`/`medium`/`low` | `critical` for production issues |
| `category` | `workflow`/`code_quality`/`verification`/`communication`/`project_specific` | `workflow` |
| `trigger` | What action caused the problem | "Pushed code referencing images without committing them" |
| `impact` | What went wrong | "Production 404 errors - broken landing page" |
| `prevention` | How to prevent in future | "Run git status to check untracked files before pushing" |
| `keywords` | Keywords for matching | `["git", "images", "assets", "push"]` |

**Example call:**
```json
{
  "title": "Always verify assets in git before pushing code references",
  "severity": "critical",
  "category": "workflow",
  "trigger": "Pushed code referencing /screenshots/*.png without committing images",
  "impact": "Production 404 errors - broken landing page",
  "prevention": "Run 'git status' to check untracked files before pushing code that references static assets",
  "keywords": ["git", "images", "assets", "push", "404", "static"]
}

Why this matters:

• Lessons are surfaced automatically in session_init and context_smart
• Future sessions will warn you before repeating the same mistake
• This prevents production issues and user frustration

Severity guide:

• critical: Production outages, data loss, security issues
• high: Breaking changes, significant user impact
• medium: Workflow inefficiencies, minor bugs
• low: Style/preference corrections

#### Codex CLI

For Codex CLI, create an `AGENTS.md` file in your project root (project rules) or in `~/.codex/AGENTS.md` (global rules) to provide rules to Codex:

Important: Codex vs Claude Tool Names

**Codex CLI** uses raw MCP tool names (e.g., `session_init`).**Claude Code** uses namespaced tool names (e.g., `mcp__contextstream__session_init`). Use the correct format for your AI tool.

AGENTS.md (Minimal)

- First user message: session_init(folder_path="<cwd>", context_hint="<user_message>"), then answer.
- Every user message: context_smart(user_message="<user_message>", format="minified", max_tokens=400) BEFORE answering.
  - Use max_tokens=200 for trivial/local edits, max_tokens=800 for deep debugging/architecture.
- If prior context is missing or user asks past decisions: session_recall(query="<question>"), then answer.
- After meaningful work/decisions/preferences: session_capture(event_type=decision|preference|task|insight, title="…", content="…").
- On frustration/corrections/tool mistakes: session_capture_lesson(...).

AGENTS.md (Full)

Message	What to Call
1st message	session_init(folder_path="...", context_hint="<user's message>")
2nd+ messages	context_smart(user_message="<user's message>")
After completing task	session_capture(...) - MUST capture decisions/insights
User frustration/correction	session_capture_lesson(...) - MUST capture lessons

---

---

When	Tool	Example
User makes a decision	session_capture	"Let's use PostgreSQL" → capture as decision
User states preference	session_capture	"I prefer TypeScript" → capture as preference
You complete a task	session_capture	Capture what was done, decisions made
Need past context	session_recall	"What did we decide about X?"

---

First message of conversation:

1. Call session_init(folder_path="<cwd>", context_hint="<user's message>")
2. Then respond

Every subsequent message:

1. Call context_smart(user_message="<user's message>") FIRST
2. Then respond

After completing a task:

1. Call session_capture to save decisions, preferences, or insights
2. This is NOT optional

When user asks about past decisions:

• Use session_recall - do NOT ask user to repeat themselves

---

You MUST immediately call session_capture_lesson with:

Windsurf

For Windsurf, create a .windsurfrules file in your project root or add to your global ~/.codeium/windsurf/memories/global_rules.md:

.windsurfrules (Minimal)

.windsurfrules (Full)

---

When the user expresses frustration, corrects you, or points out a mistake, IMMEDIATELY call:

session_capture_lesson({ title: "What to remember", severity: "critical|high|medium|low", category: "workflow|code_quality|verification|communication|project_specific", trigger: "What action caused the problem", impact: "What went wrong", prevention: "How to prevent in future", keywords: ["relevant", "search", "terms"] })

**Severity:** critical=production issues, high=breaking changes, medium=bugs, low=preferences

---

| When | Tool |
|------|------|
| User makes a decision | `session_capture` with event_type="decision" |
| User states preference | `session_capture` with event_type="preference" |
| User corrects/frustration | `session_capture_lesson` with severity + prevention |
| Need past context | `session_recall` |

**You MUST capture after completing any significant task.**

Kilo Code

For Kilo Code, create a Markdown file in .kilocode/rules/:

.kilocode/rules/contextstream.md (Minimal)

.kilocode/rules/contextstream.md (Full)

---

---

#### Cline

For Cline, create a `.clinerules` file in your project root or use the `.clinerules/` folder:

.clinerules (Minimal)

.clinerules (Full)

---

---

Roo Code

For Roo Code, create a .roorules file or use the .roo/rules/ folder:

.roorules (Minimal)

.roorules (Full)

---

---

Auto-Generate Rules

You can also ask the AI to generate these rules automatically by saying:"Use generate\_editor\_rules to create ContextStream rules for this project"

## Lessons Learned System

Learn From Mistakes - Never Repeat Them

The Lessons System captures mistakes, corrections, and user frustrations so AI assistants never repeat the same errors. Lessons are automatically surfaced in `session_init` and `context_smart` responses when relevant.

### When to Capture Lessons

Lessons should be captured automatically when any of these situations occur:

| Trigger           | Example User Message                              | Severity    |
| ----------------- | ------------------------------------------------- | ----------- |
| Production issue  | "The site is down because of that change"         | critical    |
| User frustration  | "NO! I told you NOT to do that", "WTF", caps lock | high        |
| Correction        | "That's wrong, you should...", "Fix this"         | medium      |
| Breaking change   | "This broke the tests", "The build failed"        | medium/high |
| Preference stated | "I prefer it this way", "Always do X instead"     | low         |

### Lesson Fields Explained

| Field      | Description                                                             | Example                                                  |
| ---------- | ----------------------------------------------------------------------- | -------------------------------------------------------- |
| title      | What to remember (imperative)                                           | "Always verify assets in git before pushing"             |
| severity   | critical, high, medium, low                                             | "critical" for production issues                         |
| category   | workflow, code\_quality, verification, communication, project\_specific | "workflow"                                               |
| trigger    | What action caused the problem                                          | "Pushed code referencing images without committing them" |
| impact     | What went wrong                                                         | "Production 404 errors - broken landing page"            |
| prevention | How to prevent in future                                                | "Run git status to check untracked files before pushing" |
| keywords   | Keywords for matching in future contexts                                | \["git", "images", "assets", "push"\]                    |

### Full Example

session\_capture\_lesson call

// User says: "OH COME ON! You pushed the code but the images are missing // and now the production site shows broken images!"

session_capture_lesson({ title: "Always verify assets in git before pushing code references", severity: "critical", category: "workflow", trigger: "Pushed code referencing /screenshots/*.png without committing images", impact: "Production 404 errors - broken landing page with missing images", prevention: "Run 'git status' to check untracked files before pushing code that references static assets", keywords: ["git", "images", "assets", "push", "404", "static", "screenshots"] })

### How Lessons Are Surfaced

Captured lessons are automatically returned in future sessions when relevant:

#### `session_init`

High and critical severity lessons from this workspace are included in session initialization, warning the AI before it can make the same mistake.

#### `context_smart`

When the AI asks for context, lessons matching the query keywords are included. E.g., asking about "git push" surfaces lessons with "git" or "push" keywords.

### Retrieving Lessons

Use `session_get_lessons` to retrieve and filter lessons:

session\_get\_lessons examples

// Get all critical lessons session_get_lessons({ severity: "critical" })

// Get workflow lessons session_get_lessons({ category: "workflow" })

// Search for relevant lessons session_get_lessons({ query: "git push images" })

// Combine filters session_get_lessons({ category: "verification", severity: "high", limit: 5 })

**Pro tip:** Add rules to your editor (see Editor AI Rules section above) to automatically capture lessons when users express frustration or corrections. This builds a knowledge base that prevents repeated mistakes.

## MCP Tools

See the full MCP tool reference (PRO badges and common usage examples).

View MCP Tools Reference

Looking for token-efficient workflows? See Token Saving.

## Usage Examples

Once connected, you can ask your AI assistant things like:

"Remember that we decided to use PostgreSQL for the database"

"What were our previous decisions about authentication?"

"Search our codebase for how we handle API rate limiting"

"Show me related context about the payment system"

### Lesson Examples

The AI should automatically capture lessons when you express frustration or corrections:

User says:

"NO! You pushed without running tests and now production is broken!"

→ AI captures lesson with severity: critical, category: verification

User says:

"That's wrong. Always use snake\_case for database columns, not camelCase."

→ AI captures lesson with severity: medium, category: code\_quality

User says:

"I prefer TypeScript strict mode. Please always enable it."

→ AI captures lesson with severity: low, category: project\_specific

These lessons are automatically surfaced in future sessions when relevant context is requested.

## Troubleshooting

### MCP server not starting

Ensure Node.js 18+ is installed and `npx` is available in your PATH. Try running `npx @contextstream/mcp-server` manually to check for errors.

### Authentication errors

Verify your API key is correct and has not expired. You can generate a new key from your ContextStream dashboard.

### Tools not appearing

Restart your AI application after modifying the config. Check the application logs for MCP connection errors.

### No workspace found (first-time setup)

If your account has no workspaces yet, ContextStream will prompt your AI assistant to ask you for a workspace name. The current folder will be created as a project. See MCP Tools for `workspace_bootstrap`.

## Next Steps

### Lessons Learned

Capture mistakes, never repeat them

### Memory Events

Learn about memory types

### Semantic Search

Search by meaning