MCP Connections

1. Setting up the MCP Server in Terminal

Starting Cipher as an MCP Server

To run cipher as an MCP server, you need to provide all required environment variables for the agent to function properly:

# Start cipher as MCP server (uses default agent config)
cipher --mode mcp

# Or with custom agent configuration
cipher --agent ./cipher.yml --mode mcp

Note: The --agent flag is optional and defaults to memAgent/cipher.yml if not provided.

Required Environment Variables

For cipher to function as an MCP server, you only need these required variables:

# Required: OpenAI API key (used for embeddings even with other LLM providers)
export OPENAI_API_KEY="your-openai-api-key"

# Required based on your LLM provider configuration in cipher.yml:
# - If using Anthropic provider:
export ANTHROPIC_API_KEY="your-anthropic-api-key"
# - If using OpenRouter provider:
export OPENROUTER_API_KEY="your-openrouter-api-key"
# - If using Ollama provider:
export OLLAMA_BASE_URL="http://localhost:11434"

Note: By default, cipher uses in-memory storage for vectors, cache, and database. All other configuration options are optional and have sensible defaults. For advanced configuration options including external databases, Redis, vector stores, and knowledge graphs, see the Configuration pages.

Additional Environment Variables (Optional)

Beyond the required API keys, you can customize cipher’s behavior by exporting additional environment variables to your MCP server configuration, which can be found in the .env.example file.

Custom Agent Configuration

Beside, you can create a custom cipher.yml configuration file and use the --agent flag to specify your own agent configuration:

# Create a custom configuration file
# my-cipher-config.yml

# Use it with the --agent flag
cipher --agent /path/to/my-cipher-config.yml --mode mcp

Example custom configuration file (custom-cipher.yml):

systemPrompt: |
  You are a specialized code navigation assistant with enhanced memory.
  You excel at understanding codebases, tracking architecture patterns,
  and helping developers navigate complex projects efficiently.

llm:
  provider: anthropic
  model: claude-3-5-haiku-20241022
  apiKey: $ANTHROPIC_API_KEY
  maxIterations: 30

evalLlm:
  provider: anthropic  
  model: claude-3-7-sonnet-20250219
  apiKey: $ANTHROPIC_API_KEY

mcpServers:
  filesystem:
    type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-filesystem'
      - .
    connectionMode: strict

sessions:
  maxSessions: 25
  sessionTTL: 7200000  # 2 hours

For detailed configuration options, see the Configuration Overview page.

Example Setup

Create a shell script to start cipher with required variables:

#!/bin/bash
# cipher-mcp.sh

# Set required environment variables
export OPENAI_API_KEY="your-openai-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"  # Only if using Anthropic provider

# Start cipher as MCP server
cipher --mode mcp

2. In Cursor

Cursor IDE uses an mcp.json configuration file to connect to MCP servers. Here’s how to set up cipher integration:

Configuration Location

Create or edit your mcp.json file in your Cursor settings:

{
  "mcpServers": {
    "cipher": {
      "command": "cipher",
      "args": ["--mode", "mcp"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
        // Add additional environment variables here for customization
        // "VECTOR_STORE_TYPE": "qdrant",
        // "KNOWLEDGE_GRAPH_ENABLED": "true",
        // "MAX_ITERATIONS": "30"
      }
    }
  }
}

Advanced Configuration: You can also use a custom agent configuration by modifying the args:

{
  "mcpServers": {
    "cipher": {
      "command": "cipher", 
      "args": ["--agent", "/path/to/your/custom-cipher.yml", "--mode", "mcp"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
      }
    }
  }
}

3. In Codex

Codex uses a TOML configuration file to connect to MCP servers. Here’s how to set up cipher integration:

Configuration Location

Open or create the configuration file at ~/.codex/config.toml and add the cipher server configuration:

[mcp_servers.byterover-cipher]
command = "cipher"
args = ["--mode", "mcp"]
env = {OPENAI_API_KEY="your-openai-api-key", ANTHROPIC_API_KEY="your-anthropic-api-key"}

Advanced Configuration: You can also use a custom agent configuration by modifying the args:

[mcp_servers.byterover-cipher]
command = "cipher"
args = ["--agent", "/path/to/your/custom-cipher.yml", "--mode", "mcp"]
env = {OPENAI_API_KEY="your-openai-api-key", ANTHROPIC_API_KEY="your-anthropic-api-key"}

Additional Environment Variables (Optional)

You can add more environment variables for advanced configuration:

[mcp_servers.byterover-cipher]
command = "cipher"
args = ["--mode", "mcp"]
env = {
  OPENAI_API_KEY="your-openai-api-key",
  ANTHROPIC_API_KEY="your-anthropic-api-key",
  VECTOR_STORE_TYPE="qdrant",
  KNOWLEDGE_GRAPH_ENABLED="true",
  MAX_ITERATIONS="30"
}

4. In Claude Desktop

Claude Desktop uses the claude_desktop_config.json file for MCP server configuration. The setup is similar to Cursor but with a different file location.

Configuration Schema

{
  "mcpServers": {
    "cipher": {
      "command": "cipher",
      "args": ["--mode", "mcp"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
        // Add additional environment variables here for customization
        // "VECTOR_STORE_TYPE": "qdrant",
        // "KNOWLEDGE_GRAPH_ENABLED": "true",
        // "MAX_ITERATIONS": "30"
      }
    }
  }
}

Advanced Configuration with Custom Agent: You can also specify a custom agent configuration:

{
  "mcpServers": {
    "cipher": {
      "command": "cipher", 
      "args": ["--agent", "/path/to/your/custom-cipher.yml", "--mode", "mcp"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
      }
    }
  }
}

5. Claude Code

Claude Code is Anthropic’s official CLI for Claude that supports MCP server integration. Here’s how to set up cipher with Claude Code:

Prerequisites

Install Claude Code if you haven’t already. Follow the instructions at the official documentation.

Configuration Methods

Claude Code offers multiple ways to configure MCP servers:

Method 1: CLI Wizard (Recommended)

Use the built-in CLI wizard to add cipher:

# Add cipher as a user-scoped server (available across all projects)
claude mcp add cipher -s user -e OPENAI_API_KEY=your-openai-api-key -e ANTHROPIC_API_KEY=your-anthropic-api-key -- cipher --mode mcp

# Add cipher as a project-scoped server (specific to current project)
claude mcp add cipher -s project -e OPENAI_API_KEY=your-openai-api-key -e ANTHROPIC_API_KEY=your-anthropic-api-key -- cipher --mode mcp

Method 2: JSON Configuration

Add cipher using JSON configuration:

claude mcp add-json cipher '{"type":"stdio","command":"cipher","args":["--mode","mcp"],"env":{"OPENAI_API_KEY":"your-openai-api-key","ANTHROPIC_API_KEY":"your-anthropic-api-key"}}'

Method 3: Direct Configuration File Editing

Edit the .mcp.json file in your project root or user config directory:

{
  "mcpServers": {
    "cipher": {
      "type": "stdio",
      "command": "cipher",
      "args": ["--mode", "mcp"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
        // Add additional environment variables here for customization
        // "VECTOR_STORE_TYPE": "qdrant",
        // "KNOWLEDGE_GRAPH_ENABLED": "true",
        // "MAX_ITERATIONS": "30"
      }
    }
  }
}

Managing MCP Servers

# List all configured MCP servers
claude mcp list

# Reset approval choices for project-scoped servers
claude mcp reset-project-choices

Using Cipher with Claude Code

Once configured, start Claude Code and you’ll see the MCP tools icon indicating cipher is available:

# Start Claude Code
claude

# Start with a specific project
claude --project /path/to/your/project

You can then access cipher’s capabilities including memory management, LLM integration, reasoning tools, and vector search features.

6. Gemini CLI

Gemini CLI supports MCP (Model Context Protocol) servers, allowing you to connect cipher as an external tool. Here’s how to configure cipher with Gemini CLI:

Prerequisites

Install Gemini CLI:

# Install Gemini CLI
npm install -g @google/gemini-cli

Configuration

Add cipher to your Gemini CLI settings.json file:

{
  "mcpServers": {
    "cipher": {
      "command": "cipher",
      "args": ["--mode", "mcp"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
        // Add additional environment variables here for customization
        // "VECTOR_STORE_TYPE": "qdrant",
        // "KNOWLEDGE_GRAPH_ENABLED": "true",
        // "MAX_ITERATIONS": "30"
      },
      "timeout": 15000
    }
  }
}

Usage

Once configured, cipher’s tools will be automatically available in your Gemini CLI sessions:

# Check MCP server status
gemini /mcp

# Use cipher's memory and reasoning tools through Gemini CLI
gemini "Search my project memory for authentication patterns using ask_cipher tool"

Cipher will provide Gemini CLI with access to its memory management, reasoning tools, and LLM integration capabilities.

7. Aggregator Mode

Cipher can operate in aggregator mode, acting as a comprehensive MCP server hub that connects multiple MCP servers through a single integration point. This provides enhanced tools, memory persistence, and transport flexibility.

Configuration

Add Cipher in aggregator mode to your MCP client configuration:

{
  "mcpServers": {
    "cipher": {
      "command": "cipher",
      "args": [
        "--mode",
        "mcp", 
        "--agent",
        "/path/to/cipher/examples/04-mcp-aggregator-hub/cipher.yml"
      ],
      "env": {
        "MCP_SERVER_MODE": "aggregator",
        "AGGREGATOR_TIMEOUT": "60000",
        "AGGREGATOR_CONFLICT_RESOLUTION": "prefix",
        "OPENAI_API_KEY": "your_openai_api_key",
        "EXA_API_KEY": "your_exa_api_key"
      }
    }
  }
}

Custom MCP Servers

You can extend the aggregator with your own MCP servers by adding them to the mcpServers section in cipher.yml. Cipher supports all three MCP transport types: stdio (Local Process):

your-server:
  type: stdio
  command: npx
  args: ["-y", "your-mcp-server"]
  env:
    API_KEY: $YOUR_API_KEY
  enabled: true
  timeout: 30000
  connectionMode: lenient

streamable-http (Remote HTTP Server):

your-remote-server:
  type: "streamable-http"
  url: "https://api.example.com/mcp"
  headers:
    Authorization: "Bearer token"
  enabled: true
  timeout: 30000
  connectionMode: lenient

sse (Server-Sent Events):

your-sse-server:
  type: "sse"
  url: "https://api.example.com/sse"
  headers:
    Authorization: "Bearer token"
  enabled: true
  timeout: 30000
  connectionMode: lenient

For detailed configuration options and examples, see the MCP Aggregator Hub example.

Getting Started

Configuration

Memory System

MCP Integration

Session Management

1. Setting up the MCP Server in Terminal

Starting Cipher as an MCP Server

Required Environment Variables

Additional Environment Variables (Optional)

Custom Agent Configuration

Example Setup

2. In Cursor

Configuration Location

3. In Codex

Configuration Location

Additional Environment Variables (Optional)

4. In Claude Desktop

Configuration Schema

5. Claude Code

Prerequisites

Configuration Methods

Method 1: CLI Wizard (Recommended)

Method 2: JSON Configuration

Method 3: Direct Configuration File Editing

Managing MCP Servers

Using Cipher with Claude Code

6. Gemini CLI

Prerequisites

Configuration

Usage

7. Aggregator Mode

Configuration

Custom MCP Servers

Getting Started

Configuration

Memory System

MCP Integration

Session Management

​1. Setting up the MCP Server in Terminal

​Starting Cipher as an MCP Server

​Required Environment Variables

​Additional Environment Variables (Optional)

​Custom Agent Configuration

​Example Setup

​2. In Cursor

​Configuration Location

​3. In Codex

​Configuration Location

​Additional Environment Variables (Optional)

​4. In Claude Desktop

​Configuration Schema

​5. Claude Code

​Prerequisites

​Configuration Methods

​Method 1: CLI Wizard (Recommended)

​Method 2: JSON Configuration

​Method 3: Direct Configuration File Editing

​Managing MCP Servers

​Using Cipher with Claude Code

​6. Gemini CLI

​Prerequisites

​Configuration

​Usage

​7. Aggregator Mode

​Configuration

​Custom MCP Servers

1. Setting up the MCP Server in Terminal

Starting Cipher as an MCP Server

Required Environment Variables

Additional Environment Variables (Optional)

Custom Agent Configuration

Example Setup

2. In Cursor

Configuration Location

3. In Codex

Configuration Location

Additional Environment Variables (Optional)

4. In Claude Desktop

Configuration Schema

5. Claude Code

Prerequisites

Configuration Methods

Method 1: CLI Wizard (Recommended)

Method 2: JSON Configuration

Method 3: Direct Configuration File Editing

Managing MCP Servers

Using Cipher with Claude Code

6. Gemini CLI

Prerequisites

Configuration

Usage

7. Aggregator Mode

Configuration

Custom MCP Servers