Skip to content

mcp-integration.md

Latest commit

 

History

History
307 lines (221 loc) · 5.97 KB

mcp-integration.md

File metadata and controls

307 lines (221 loc) · 5.97 KB

MCP Integration Guide

This guide explains how to integrate CocoIndex with Claude Code using the Model Context Protocol (MCP).

What is MCP?

The Model Context Protocol (MCP) is a standard for connecting AI assistants like Claude to external tools and data sources. It allows Claude Code to:

  • Search your documents semantically
  • Index new documents
  • Retrieve metadata
  • Access your knowledge base directly

Configuration

Step 1: Locate Your Claude Code Config

The Claude Code configuration file is located at:

  • macOS/Linux: ~/.claude.json
  • Windows: %USERPROFILE%\.claude.json

Step 2: Add the MCP Server

Add the following to your ~/.claude.json:

{
  "mcpServers": {
    "cocoindex": {
      "command": "/path/to/cocoindex-claude-code/.venv/bin/python",
      "args": ["/path/to/cocoindex-claude-code/mcp_server.py"],
      "env": {
        "COCOINDEX_DATABASE_URL": "postgres://cocoindex:cocoindex@localhost/cocoindex",
        "OPENAI_API_KEY": "your-openai-key-here"
      }
    }
  }
}

Step 3: Use Absolute Paths

Important: Always use absolute paths, not relative paths.

To find your paths:

cd cocoindex-claude-code
echo "Python: $(pwd)/.venv/bin/python"
echo "Script: $(pwd)/mcp_server.py"

Step 4: Restart Claude Code

After updating the configuration:

# Exit Claude Code
# Press Ctrl+C or type /exit

# Restart
claude

Available Tools

Once connected, Claude Code has access to these tools:

cocoindex_search

Search indexed documents using semantic similarity.

Parameters:

Parameter Type Required Description
query string Yes Search query
limit integer No Max results (default: 5)

Example usage in Claude Code:

> Search my documents for API authentication patterns

cocoindex_index

Trigger re-indexing of all documents.

Parameters: None

Example:

> Re-index my documents

cocoindex_list

List all documents currently in the index.

Parameters: None

Example:

> What documents are in my knowledge base?

cocoindex_metadata

Get LLM-extracted metadata for a specific document.

Parameters:

Parameter Type Required Description
filename string Yes Document filename

Example:

> Get the metadata for README.md

cocoindex_add

Add a new document to the index.

Parameters:

Parameter Type Required Description
filename string Yes Filename for the document
content string Yes Document content

Example:

> Add this note to my knowledge base as "meeting-notes.md"

How It Works

sequenceDiagram
    participant U as You
    participant CC as Claude Code
    participant MCP as MCP Server
    participant CI as CocoIndex
    participant DB as PostgreSQL

    U->>CC: "Find docs about authentication"
    Note over CC: Claude decides to use<br/>cocoindex_search tool

    CC->>MCP: tools/call: cocoindex_search
    Note over MCP: JSON-RPC over stdio

    MCP->>CI: search("authentication", limit=5)
    CI->>DB: Vector similarity query
    DB-->>CI: Matching chunks
    CI-->>MCP: QueryOutput

    MCP-->>CC: JSON results
    CC-->>U: "I found 3 relevant documents..."
Loading

Protocol Details

The MCP server uses JSON-RPC 2.0 over stdio (standard input/output).

Initialization

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": {"name": "cocoindex-mcp", "version": "1.0.0"},
    "capabilities": {"tools": {}}
  }
}

Tool Discovery

{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}

Tool Invocation

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "cocoindex_search",
    "arguments": {"query": "authentication", "limit": 5}
  }
}

Troubleshooting MCP Connection

Check if MCP Server Works

Test the MCP server manually:

cd cocoindex-claude-code
source .venv/bin/activate
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python mcp_server.py

You should see a JSON response.

Common Issues

"MCP server not found"

  • Check that paths are absolute, not relative
  • Verify the Python path exists: ls -la /path/to/.venv/bin/python
  • Ensure the script path exists: ls -la /path/to/mcp_server.py

"Connection refused" or database errors

  • Make sure PostgreSQL is running: docker compose -f docker/compose.yaml ps
  • Start if needed: docker compose -f docker/compose.yaml up -d

"No results found"

  • Index your documents first: cocoindex update main.py
  • Check that documents exist: ls data/documents/

Enable Debug Logging

Add to your environment:

export COCOINDEX_LOG_LEVEL=DEBUG

Security Considerations

API Keys

The MCP server needs access to your API keys. You can provide them via:

  1. Environment variables in config:
{
  "env": {
    "OPENAI_API_KEY": "sk-..."
  }
}
  1. System environment:
export OPENAI_API_KEY="sk-..."
  1. .env file in the project directory

Database Access

The default configuration uses a local PostgreSQL instance with basic credentials. For production:

  • Use strong passwords
  • Restrict network access
  • Consider encryption at rest

Advanced Configuration

Custom Database

{
  "env": {
    "COCOINDEX_DATABASE_URL": "postgres://user:pass@host:port/dbname"
  }
}

Multiple Knowledge Bases

You can run multiple instances with different namespaces:

{
  "mcpServers": {
    "cocoindex-work": {
      "command": "...",
      "env": {
        "COCOINDEX_APP_NAMESPACE": "work"
      }
    },
    "cocoindex-personal": {
      "command": "...",
      "env": {
        "COCOINDEX_APP_NAMESPACE": "personal"
      }
    }
  }
}