MCP Integration

Model Context Protocol (MCP) integration allows Cipher to work seamlessly with MCP-compatible clients like Claude Desktop, Cursor, Windsurf, and other AI coding assistants.

Overview

Cipher can run as an MCP server, exposing its memory and reasoning capabilities to any MCP client. This enables persistent memory across different AI tools and coding environments.

Quick Setup

Basic MCP Configuration

To use Cipher as an MCP server in your MCP client:

{
	"mcpServers": {
		"cipher": {
			"type": "stdio",
			"command": "cipher",
			"args": ["--mode", "mcp"],
			"env": {
				"OPENAI_API_KEY": "your_openai_api_key",
				"ANTHROPIC_API_KEY": "your_anthropic_api_key"
			}
		}
	}
}

Environment Variables for MCP

When running in MCP mode, export all environment variables as Cipher won't read from .env file:

export OPENAI_API_KEY="sk-your-openai-key"
export ANTHROPIC_API_KEY="sk-ant-your-anthropic-key"
export VECTOR_STORE_TYPE="qdrant"
export VECTOR_STORE_URL="your-qdrant-endpoint"
export VECTOR_STORE_API_KEY="your-qdrant-api-key"

Transport Types

Cipher supports multiple MCP transport protocols:

STDIO Transport (Default)

Standard input/output transport - most widely supported:

{
	"mcpServers": {
		"cipher": {
			"type": "stdio",
			"command": "cipher",
			"args": ["--mode", "mcp"],
			"env": {
				"OPENAI_API_KEY": "sk-your-key"
			}
		}
	}
}

SSE Transport (Server-Sent Events)

Real-time transport over HTTP. Endpoint: /sse.

# Start Cipher with SSE transport
cipher --mode mcp --mcp-transport-type sse --mcp-port 4000

{
  "mcpServers": {
    "cipher-sse": {
      "url": "http://localhost:4000/sse"
    }
  }
}

Streamable-HTTP Transport

HTTP request/response with streaming. Endpoint base: /http.

# Start Cipher with streamable-HTTP transport
cipher --mode mcp --mcp-transport-type streamable-http --mcp-port 4000

{
  "mcpServers": {
    "cipher-http": {
      "url": "http://localhost:4000/http"
    }
  }
}

Note: Clients must send the correct Accept headers per spec. Examples:

GET /http: Accept: text/event-stream
POST /http: Accept: application/json, text/event-stream and Content-Type: application/json

MCP Server Modes

Cipher offers two distinct MCP server modes controlled by the MCP_SERVER_MODE environment variable.

Default Mode

Exposes only the ask_cipher tool - simple and focused:

{
	"mcpServers": {
		"cipher-default": {
			"type": "stdio",
			"command": "cipher", 
			"args": ["--mode", "mcp"],
			"env": {
				"OPENAI_API_KEY": "sk-your-key",
				"MCP_SERVER_MODE": "default"
			}
		}
	}
}

Available Tools:

ask_cipher - Main conversational interface to Cipher

Aggregator Mode

Exposes all available tools including memory tools and connected MCP server tools:

{
	"mcpServers": {
		"cipher-aggregator": {
			"type": "stdio",
			"command": "cipher",
			"args": ["--mode", "mcp"], 
			"env": {
				"OPENAI_API_KEY": "sk-your-key",
				"MCP_SERVER_MODE": "aggregator",
				"AGGREGATOR_CONFLICT_RESOLUTION": "prefix",
				"AGGREGATOR_TIMEOUT": "60000"
			}
		}
	}
}

Available Tools:

All built-in Cipher tools:
- ask_cipher - Main conversational interface
- cipher_memory_search - Search stored memories
- cipher_extract_and_operate_memory - Extract and store memories
- cipher_store_reasoning_memory - Store reasoning patterns
- cipher_search_reasoning_patterns - Search reasoning history
Plus all tools from connected MCP servers (defined in cipher.yml)

Aggregator Configuration

Environment Variables

Variable	Description	Options	Default
`MCP_SERVER_MODE`	Server mode	`default`, `aggregator`	`default`
`USE_ASK_CIPHER`	Enable/disable ask_cipher tool (only LLM-requiring tool)	`true`, `false`	`false`
`AGGREGATOR_CONFLICT_RESOLUTION`	Handle tool name conflicts	`prefix`, `first-wins`, `error`	`prefix`
`AGGREGATOR_TIMEOUT`	Tool execution timeout (ms)	Number	`60000`

Note: When USE_ASK_CIPHER=false, the ask_cipher tool is disabled, which is the only tool requiring LLM functionality. However, API keys are still required for embedding models used by memory and reasoning tools (cipher_memory_search, cipher_extract_and_operate_memory, etc.).

Conflict Resolution Strategies

prefix (Recommended):

# Tools are prefixed with server name
filesystem__read_file  # from filesystem server
memory__search         # from memory server

first-wins:

# First server with tool name wins
read_file             # from whichever server registered first

error:

# Throws error if tool names conflict
Error: Tool name conflict detected

IDE Configurations

Claude Desktop

Add to your Claude Desktop MCP configuration:

macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
	"mcpServers": {
		"cipher": {
			"type": "stdio",
			"command": "cipher",
			"args": ["--mode", "mcp"],
			"env": {
				"OPENAI_API_KEY": "sk-your-openai-key",
				"ANTHROPIC_API_KEY": "sk-ant-your-anthropic-key",
				"VECTOR_STORE_TYPE": "qdrant",
				"VECTOR_STORE_URL": "your-qdrant-endpoint",
				"VECTOR_STORE_API_KEY": "your-qdrant-key"
			}
		}
	}
}

Cursor

Add to Cursor's MCP configuration. Cursor URL entries are treated as SSE:

{
  "mcpServers": {
    "cipher-sse": { "url": "http://localhost:4000/sse" }
  }
}

Windsurf

Similar to Claude Desktop configuration:

{
	"mcpServers": {
		"cipher-memory": {
			"type": "stdio",
			"command": "cipher",
			"args": ["--mode", "mcp"],
			"env": {
				"OPENAI_API_KEY": "sk-your-openai-key",
				"USE_WORKSPACE_MEMORY": "true"
			}
		}
	}
}

Claude Code

For Claude Code integration:

{
	"mcpServers": {
		"cipher": {
			"type": "stdio",
			"command": "cipher",
			"args": ["--mode", "mcp"],
			"env": {
				"OPENAI_API_KEY": "sk-your-openai-key",
				"MCP_SERVER_MODE": "aggregator"
			}
		}
	}
}

Advanced Configurations

Workspace Memory Integration

Enable team-aware memory for collaborative environments:

{
	"mcpServers": {
		"cipher-workspace": {
			"type": "stdio",
			"command": "cipher",
			"args": ["--mode", "mcp"],
			"env": {
				"OPENAI_API_KEY": "sk-your-openai-key",
				"USE_WORKSPACE_MEMORY": "true",
				"WORKSPACE_VECTOR_STORE_COLLECTION": "team_project",
				"DISABLE_DEFAULT_MEMORY": "false"
			}
		}
	}
}

Multiple Cipher Instances

Run different Cipher configurations for different projects:

{
	"mcpServers": {
		"cipher-frontend": {
			"type": "stdio", 
			"command": "cipher",
			"args": ["--mode", "mcp", "--agent", "/path/to/frontend-config.yml"],
			"env": {
				"OPENAI_API_KEY": "sk-your-key",
				"VECTOR_STORE_COLLECTION": "frontend_memory"
			}
		},
		"cipher-backend": {
			"type": "stdio",
			"command": "cipher", 
			"args": ["--mode", "mcp", "--agent", "/path/to/backend-config.yml"],
			"env": {
				"OPENAI_API_KEY": "sk-your-key",
				"VECTOR_STORE_COLLECTION": "backend_memory"
			}
		}
	}
}

Custom Tool Timeout

For long-running operations:

{
	"mcpServers": {
		"cipher-heavy": {
			"type": "stdio",
			"command": "cipher",
			"args": ["--mode", "mcp", "--timeout", "300000"],
			"env": {
				"OPENAI_API_KEY": "sk-your-key",
				"AGGREGATOR_TIMEOUT": "300000"
			}
		}
	}
}

MCP Aggregator Hub Example

Check out the MCP Aggregator Hub example that demonstrates:

Exposing filesystem tools alongside memory tools
Conflict resolution in action
Tool prefixing and namespacing
Integration with multiple MCP servers

Troubleshooting

Common Issues

Tool Not Available:

{
  "error": "Tool 'cipher_memory_search' not found"
}

Solution: Set MCP_SERVER_MODE=aggregator to expose memory tools.

Connection Refused:

{
  "error": "Failed to connect to Cipher MCP server"
}

Solutions:

Ensure Cipher is installed: npm install -g @byterover/cipher
Check environment variables are exported
Verify the command path in MCP config

Environment Variable Issues:

Error: OPENAI_API_KEY not found

Solution: Export variables before starting MCP client:

export OPENAI_API_KEY="sk-your-key"
# Then start your MCP client

Tool Name Conflicts:

{
  "error": "Tool name conflict: read_file"
}

Solution: Set AGGREGATOR_CONFLICT_RESOLUTION=prefix or use first-wins.

Debug Mode

Enable debug logging:

{
	"mcpServers": {
		"cipher-debug": {
			"type": "stdio",
			"command": "cipher",
			"args": ["--mode", "mcp"],
			"env": {
				"OPENAI_API_KEY": "sk-your-key",
				"DEBUG": "cipher:*",
				"MCP_LOG_LEVEL": "debug"
			}
		}
	}
}

Testing MCP Connection

Test your MCP setup:

# Start Cipher MCP server manually
export OPENAI_API_KEY="sk-your-key"
cipher --mode mcp

# Test with MCP client tools
npx @modelcontextprotocol/inspector cipher --mode mcp

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MCP Integration

Overview

Quick Setup

Basic MCP Configuration

Environment Variables for MCP

Transport Types

STDIO Transport (Default)

SSE Transport (Server-Sent Events)

Streamable-HTTP Transport

MCP Server Modes

Default Mode

Aggregator Mode

Aggregator Configuration

Environment Variables

Conflict Resolution Strategies

IDE Configurations

Claude Desktop

Cursor

Windsurf

Claude Code

Advanced Configurations

Workspace Memory Integration

Multiple Cipher Instances

Custom Tool Timeout

MCP Aggregator Hub Example

Troubleshooting

Common Issues

Debug Mode

Testing MCP Connection

Related Documentation

FilesExpand file tree

mcp-integration.md

Latest commit

History

mcp-integration.md

File metadata and controls

MCP Integration

Overview

Quick Setup

Basic MCP Configuration

Environment Variables for MCP

Transport Types

STDIO Transport (Default)

SSE Transport (Server-Sent Events)

Streamable-HTTP Transport

MCP Server Modes

Default Mode

Aggregator Mode

Aggregator Configuration

Environment Variables

Conflict Resolution Strategies

IDE Configurations

Claude Desktop

Cursor

Windsurf

Claude Code

Advanced Configurations

Workspace Memory Integration

Multiple Cipher Instances

Custom Tool Timeout

MCP Aggregator Hub Example

Troubleshooting

Common Issues

Debug Mode

Testing MCP Connection

Related Documentation