MCP Integration

Connect Your AI Tools

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

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

Prerequisites

A ContextStream account with an API key
Node.js 18+ installed on your system

Cursor / VS Code

Add ContextStream to your Cursor or VS Code MCP configuration:

.cursor/mcp.json or .vscode/mcp.json

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

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

[mcpServers.contextstream]
command = "npx"
args = ["-y", "@contextstream/mcp-server"]

[mcpServers.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 using the CLI command:

Terminal

claude mcp add contextstream -e CONTEXTSTREAM_API_URL=https://api.contextstream.io -e CONTEXTSTREAM_API_KEY=your_api_key -- npx -y @contextstream/mcp-server

Or manually edit your settings file at ~/.claude/settings.json:

~/.claude/settings.json

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

After adding the MCP server, restart Claude Code for changes to take effect. You can verify the server is loaded by running claude mcp list.

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

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

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

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

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

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

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)

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

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)

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

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.

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`

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
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.

Add this content to your rules file. Here are 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

## 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 |

**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:**
- `session_init` returns the last ~10 items **BY TIME** (chronological)
- `context_smart` **SEARCHES** for items **RELEVANT to THIS message** (semantic)

**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 |
| Need past context | `mcp__contextstream__session_recall` | "What did we decide about X?" |

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

Windsurf

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

.windsurfrules (or global_rules.md)

## 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** | `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 |

**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:**
- `session_init` returns the last ~10 items **BY TIME** (chronological)
- `context_smart` **SEARCHES** for items **RELEVANT to THIS message** (semantic)

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

---

### When to Capture (MANDATORY)

| 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 |
| Need past context | `session_recall` | "What did we decide about X?" |

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

---

### Quick Examples

```
# First message - user asks about auth
session_init(folder_path="/path/to/project", context_hint="how should I implement auth?")

# Second message - user asks about database
context_smart(user_message="what database should I use?")
# Returns: W:Maker|P:myproject|D:Use PostgreSQL|D:No ORMs|M:DB schema at...

# User says "Let's use Redis for caching"
session_capture(event_type="decision", title="Caching Choice", content="Using Redis")

# Check past decisions
session_recall(query="what did we decide about caching?")
```

Kilo Code

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

.kilocode/rules/contextstream.md

## 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** | `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 |

**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:**
- `session_init` returns the last ~10 items **BY TIME** (chronological)
- `context_smart` **SEARCHES** for items **RELEVANT to THIS message** (semantic)

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

---

### When to Capture (MANDATORY)

| 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 |
| Need past context | `session_recall` | "What did we decide about X?" |

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

Cline

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

.clinerules (or .clinerules/contextstream.md)

## 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** | `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 |

**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:**
- `session_init` returns the last ~10 items **BY TIME** (chronological)
- `context_smart` **SEARCHES** for items **RELEVANT to THIS message** (semantic)

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

---

### When to Capture (MANDATORY)

| 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 |
| Need past context | `session_recall` | "What did we decide about X?" |

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

Roo Code

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

.roorules (or .roo/rules/contextstream.md)

## 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** | `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 |

**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:**
- `session_init` returns the last ~10 items **BY TIME** (chronological)
- `context_smart` **SEARCHES** for items **RELEVANT to THIS message** (semantic)

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

---

### When to Capture (MANDATORY)

| 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 |
| Need past context | `session_recall` | "What did we decide about X?" |

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

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"

Token-Saving Context Tools

Save ~80% on AI Tokens

These tools let AI editors use ContextStream for context instead of including full chat history in every prompt. This dramatically reduces token usage and cost while maintaining context quality.

Instead of AI editors sending your entire conversation history with every prompt, these tools retrieve only relevant context on-demand:

Tool	Purpose	Token Usage
`context_smart`	KEY TOOL - Get minified relevant context before every response	~200 tokens
`session_summary`	Compact workspace summary for conversation start	~500 tokens
`ai_context_budget`	Get context within a specified token budget	Custom budget
`session_compress`	Extract key info from chat history, store as memory	N/A (saves data)
`session_delta`	Get incremental context changes since timestamp	~100 tokens

How context_smart Works

The AI calls context_smart with each user message to get only relevant context:

context_smart Example

# User asks: "how should I implement auth?"
# AI calls: context_smart(user_message="how should I implement auth?")
# Returns minified format:

W:Maker|P:contextstream|D:Use JWT for auth|D:No session cookies|M:Auth API at /auth/...

# Type codes: W=Workspace, P=Project, D=Decision, M=Memory, I=Insight
# ~200 tokens instead of ~5,000 tokens for full chat history

Token Savings Example

❌ Traditional (Full History)

Turn 1: 2,000 tokens
Turn 5: 10,000 tokens
Turn 10: 20,000+ tokens
Total: ~50,000 tokens

✅ With ContextStream

Turn 1: 500 tokens (summary)
Turn 5: 700 tokens (smart context)
Turn 10: 800 tokens (smart context)
Total: ~8,000 tokens (84% savings)

To enable automatic token-saving, add editor rules (see above) that instruct the AI to callcontext_smart before every response.

All 69 MCP Tools

ContextStream provides 69 MCP tools organized into categories. You don't need to memorize tool names—just ask naturally and the AI will use the right tool. Each tool below includes an example prompt you can use.

Tip: Once your session is initialized (which happens automatically), most features work by simply asking questions like "What did we decide about the database?" or "Remember that we chose React".

Essential Session Tools

Essential

session_initInitialize session and load workspace context, decisions, and memory

"Load my workspace context"

session_captureCapture decisions, preferences, bugs, features, and insights

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

session_recallSearch past context using natural language

"What did we decide about authentication?"

session_rememberQuick way to store important context

"Remember that I prefer TypeScript strict mode"

context_smartGet minified relevant context for a query (call before every response)

"Get context for implementing auth"

Token-Saving Tools

session_summaryGet compact context summary (~500 tokens)

"Get a summary of workspace context"

session_compressExtract and store key info from chat history

"Compress this chat history into memory"

ai_context_budgetGet context within a token budget

"Get auth context within 1000 tokens"

session_deltaGet changes since a timestamp

"What context changed since yesterday?"

Memory & Context

session_smart_searchSearch with automatic context enrichment

"Search for everything related to payment processing"

session_get_user_contextGet user preferences and coding style

"What are my coding preferences?"

memory_create_eventCreate structured memory events with metadata

"Create a detailed memory about the API refactoring"

memory_searchSearch existing memory and notes

"Search my notes for caching strategy"

memory_decisionsList past decisions for reference

"Show me all past decisions"

memory_timelineView chronological history of a workspace

"Show me the timeline of this workspace"

memory_summaryGet condensed summary of workspace memory

"Summarize what we've worked on"

memory_list_eventsList all memory events

"List all my saved memories"

memory_get_eventGet a specific memory event

memory_update_eventUpdate an existing memory event

"Update that memory about the database choice"

memory_delete_eventDelete a memory event

"Delete that outdated note"

memory_distill_eventExtract key insights from a memory event

"Distill the key points from that conversation"

memory_bulk_ingestBulk import multiple memory events

Knowledge Graph

memory_create_nodeCreate a knowledge node with relations

"Create a knowledge node for the User entity"

memory_list_nodesList knowledge graph nodes

"Show me all knowledge nodes"

memory_get_nodeGet a specific knowledge node

memory_update_nodeUpdate a knowledge node

memory_delete_nodeDelete a knowledge node

memory_supersede_nodeReplace a node with updated info (maintains history)

"Update the auth node with new information"

graph_relatedFind related knowledge nodes

"What's related to the User entity?"

graph_pathFind path between two nodes

"How is User related to Payment?"

graph_decisionsQuery decision history from the graph

"Show decision history for authentication"

graph_contradictionsFind contradicting information

"Are there any contradictions in our knowledge?"

Code Search

search_semanticFind code by meaning/intent (best for 'how does X work?')

"How does authentication work in this codebase?"

search_hybridCombined semantic + keyword search (most versatile)

"Find code related to user permissions"

search_keywordExact text/symbol search

"Search for handleSubmit function"

search_patternRegex pattern search

"Find all TODO comments"

search_suggestionsGet search suggestions based on partial query

"Suggest searches for auth"

AI Context Building

ai_contextBuild LLM context for a query (docs + code + memory)

"Build context for implementing user roles"

ai_enhanced_contextDeeper analysis with more context

"Give me deep context on the payment system"

ai_embeddingsGenerate embeddings for text

ai_planGenerate development plan from description

"Create a plan to add email notifications"

ai_tasksGenerate tasks from plan or description

"Break down the auth refactor into tasks"

Code Analysis

graph_dependenciesFind what a file/function depends on

"What does UserService depend on?"

graph_impactAnalyze impact of changing something

"What would be affected if I change the User model?"

graph_call_pathTrace call paths between functions

"How does login() eventually call the database?"

graph_circular_dependenciesDetect circular imports/dependencies

"Are there any circular dependencies?"

graph_unused_codeFind dead/unused code

"Find unused code in this project"

Project Management

projects_listList all projects

"Show me all my projects"

projects_getGet project details

"Get details about this project"

projects_createCreate a new project

"Create a new project called backend-api"

projects_updateRename or update a project

"Rename this project to backend-service"

projects_deleteDelete a project and its contents

"Delete the old-api project"

projects_overviewGet project summary and stats

"Give me an overview of this project"

projects_filesList indexed files in a project

"What files are indexed?"

projects_statisticsGet detailed code statistics

"Show me code statistics"

projects_indexTrigger re-indexing of project

"Re-index this project"

projects_index_statusCheck indexing status

"Is indexing complete?"

projects_ingest_localIndex a local directory

"Index the /src folder"

Workspace Organization

workspaces_listList accessible workspaces

"Show me all my workspaces"

workspaces_getGet workspace details

"Get details about this workspace"

workspaces_createCreate a new workspace

"Create a workspace called MyCompany"

workspaces_updateRename or update a workspace

"Rename this workspace to Engineering"

workspaces_deleteDelete a workspace and all its contents

"Delete the old-workspace"

workspaces_overviewGet workspace summary

"Give me a workspace overview"

workspaces_contentList content in workspace

"What's in this workspace?"

workspaces_analyticsGet workspace usage analytics

"Show workspace usage stats"

workspace_associateLink a folder to a workspace

"Associate this folder with my workspace"

Utilities

auth_meGet current user profile

"Who am I logged in as?"

generate_editor_rulesGenerate AI rules files for editors

"Generate ContextStream rules for this project"

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"

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.

Connect Your AI Tools

What is MCP?

Prerequisites

Cursor / VS Code

Codex CLI

Claude Code (CLI)

Claude Desktop (GUI App)

Windsurf (Codeium)

Cline

Kilo Code

Roo Code

Improve Automatic ContextStream Usage

Global Rules (All Projects)

Project Rules (Single Project)

Claude Code

Windsurf

Kilo Code

Cline

Roo Code

Token-Saving Context Tools

How context_smart Works

Token Savings Example

All 69 MCP Tools

Essential Session Tools

Token-Saving Tools

Memory & Context

Knowledge Graph

Code Search

AI Context Building

Code Analysis

Project Management

Workspace Organization

Utilities

Usage Examples

Troubleshooting

MCP server not starting

Authentication errors

Tools not appearing

Next Steps

Memory Events

Semantic Search