MCP Connections

Cipher can operate as an MCP server, allowing other tools and editors to connect to it and access its advanced memory capabilities, LLM integration, and reasoning tools. This guide covers how to configure cipher as an MCP server and connect it to various development environments.

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 adding additional environment variables to your MCP server configuration:

Memory & Storage Configuration

# Vector Store Configuration
VECTOR_STORE_TYPE="qdrant"              # Options: in-memory, qdrant
QDRANT_URL="http://localhost:6333"
QDRANT_API_KEY="your-qdrant-api-key"

# Knowledge Graph Configuration
KNOWLEDGE_GRAPH_ENABLED="true"
NEO4J_URI="bolt://localhost:7687"
NEO4J_USERNAME="neo4j"
NEO4J_PASSWORD="your-neo4j-password"

# Cache Configuration
CACHE_TYPE="redis"                       # Options: in-memory, redis
REDIS_URL="redis://localhost:6379"

LLM Provider Customization

# OpenAI Configuration
OPENAI_BASE_URL="https://api.openai.com/v1"
OPENAI_MODEL="gpt-4-turbo"

# OpenRouter Configuration
OPENROUTER_API_KEY="your-openrouter-key"
OPENROUTER_MODEL="anthropic/claude-3.5-sonnet"

# Ollama Configuration (for local models)
OLLAMA_BASE_URL="http://localhost:11434"
OLLAMA_MODEL="llama3.1:8b"

Agent Behavior

# Session Management
MAX_SESSIONS="100"
SESSION_TTL="3600000"                    # Session timeout in milliseconds

# Security & Privacy
REDACT_SECRETS="true"                    # Hide sensitive data in logs
LOG_LEVEL="info"                         # Options: debug, info, warn, error

# Performance
MAX_ITERATIONS="50"                      # Maximum agent reasoning iterations

Custom Agent Configuration

Instead of using environment variables, 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 (code-navigator.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

agentCard:
  name: CodeNavigator
  version: 1.0.0
  description: "Specialized code navigation assistant with persistent memory"

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/code-navigator.yml", "--mode", "mcp"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
      }
    }
  }
}

Accessing MCP Settings in Cursor

Open Cursor IDE
Go to Settings > MCP
Click “Add New MCP Server”
Configure the cipher server with the above settings
Restart Cursor to apply changes

Using Cipher in Cursor

Once configured, you can:

Access cipher’s memory capabilities through the AI assistant
Use cipher’s LLM integration for enhanced coding assistance
Leverage cipher’s reasoning tools for complex development tasks

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

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

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/code-navigator.yml", "--mode", "mcp"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
      }
    }
  }
}

Setup Steps

Create/Edit Configuration File
- Navigate to the configuration file location for your OS
- Create the file if it doesn’t exist
- Add the cipher server configuration
Restart Claude Desktop
- Close Claude Desktop completely
- Reopen the application
- The cipher server should now be available
Verify Connection
- Look for the hammer icon in the chat interface
- This indicates MCP tools are available
- You should see cipher’s tools listed when clicked

Using Cipher in Claude Desktop

Once connected, you can:

Ask Claude to access your cipher memory systems
Use cipher’s advanced reasoning capabilities
Leverage cipher’s multi-LLM integration for complex tasks
Access cipher’s vector search and knowledge management features

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

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

Troubleshooting

Common Issues

Connection Refused
- Verify all required environment variables are set
- Check that cipher is installed and accessible via cipher --version
- Ensure no other service is using the configured port
Authentication Errors
- Verify API keys are correct and not expired
- Check that API keys have necessary permissions
- Ensure environment variables are properly set
Memory/Storage Issues
- Verify storage paths exist and are writable
- Check database connection strings
- Ensure Redis is running if configured
MCP Server Not Found
- Restart your editor/IDE after configuration changes
- Verify the configuration file syntax is correct
- Check that the MCP server is properly installed

Debug Mode

Enable debug logging to troubleshoot issues:

# Enable MCP debug logging
export MCP_DEBUG=true
cipher --mode mcp

Getting Started

Configuration

Memory System

MCP Integration

Connections

MCP Connections

1. Setting up the MCP Server in Terminal

Starting Cipher as an MCP Server

Required Environment Variables

Additional Environment Variables (Optional)

Memory & Storage Configuration

LLM Provider Customization

Agent Behavior

Custom Agent Configuration

Example Setup

2. In Cursor

Configuration Location

Accessing MCP Settings in Cursor

Using Cipher in Cursor

3. In Claude Desktop

Configuration Location

Configuration Schema

Setup Steps

Using Cipher in Claude Desktop

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

5. Gemini CLI

Prerequisites

Configuration

Usage

Troubleshooting

Common Issues

Debug Mode

Getting Started

Configuration

Memory System

MCP Integration

​MCP Connections

​1. Setting up the MCP Server in Terminal

​Starting Cipher as an MCP Server

​Required Environment Variables

​Additional Environment Variables (Optional)

​Memory & Storage Configuration

​LLM Provider Customization

​Agent Behavior

​Custom Agent Configuration

​Example Setup

​2. In Cursor

​Configuration Location

​Accessing MCP Settings in Cursor

​Using Cipher in Cursor

​3. In Claude Desktop

​Configuration Location

​Configuration Schema

​Setup Steps

​Using Cipher in Claude Desktop

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

​5. Gemini CLI

​Prerequisites

​Configuration

​Usage

​Troubleshooting

​Common Issues

​Debug Mode

MCP Connections

1. Setting up the MCP Server in Terminal

Starting Cipher as an MCP Server

Required Environment Variables

Additional Environment Variables (Optional)

Memory & Storage Configuration

LLM Provider Customization

Agent Behavior

Custom Agent Configuration

Example Setup

2. In Cursor

Configuration Location

Accessing MCP Settings in Cursor

Using Cipher in Cursor

3. In Claude Desktop

Configuration Location

Configuration Schema

Setup Steps

Using Cipher in Claude Desktop

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

5. Gemini CLI

Prerequisites

Configuration

Usage

Troubleshooting

Common Issues

Debug Mode