home / mcp / codebase rag mcp server

Codebase RAG MCP Server

MCP server for code retrieval from a fully indexed codebase using CocoIndex

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "allentcm-mcp-codebase-rag": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URL",
        "-e",
        "VOYAGE_API_KEY",
        "-e",
        "EMBEDDING_TABLE",
        "-e",
        "TRACKING_TABLE",
        "-p",
        "8080:8080",
        "allentcm/mcp-codebase-rag:1.0.0"
      ],
      "env": {
        "DATABASE_URL": "postgres://cocoindex:cocoindex@localhost/cocoindex",
        "TRACKING_TABLE": "codebase__cocoindex_tracking",
        "VOYAGE_API_KEY": "voyage_api_key",
        "EMBEDDING_TABLE": "codebase__code_embeddings"
      }
    }
  }
}

You can run and interact with the Codebase RAG MCP Server to perform semantic codebase search, list tracked files, and retrieve file contents. It uses embeddings stored in PostgreSQL and exposes simple tools to query code snippets, enumerate files, and fetch file content by name.

How to use

To use the Codebase RAG MCP Server, start it and connect a compatible MCP client. You will access three core capabilities: search_codebase to find relevant code snippets based on a query, get_files to list all tracked files, and get_file_content to retrieve the complete content of a specific file by filename. Ensure your PostgreSQL database is reachable and the embedding model API key is available to enable semantic search.

How to install

Prerequisites: you need Docker installed on your machine. You may also need access to a PostgreSQL database and the Voyage embedding API key for full functionality.

Step 1: Prepare environment variables and database connections. You will supply the PostgreSQL connection string and the Voyage API key as environment variables when you run the server.

Codebase RAG MCP Server configuration

{
  "mcpServers": {
    "codebase_rag": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URL",
        "-e",
        "VOYAGE_API_KEY",
        "-e",
        "EMBEDDING_TABLE",
        "-e",
        "TRACKING_TABLE",
        "-p",
        "8080:8080",
        "allentcm/mcp-codebase-rag:1.0.0"
      ],
      "env": {
        "DATABASE_URL": "postgres://cocoindex:cocoindex@localhost/cocoindex",
        "VOYAGE_API_KEY": "voyage_api_key",
        "EMBEDDING_TABLE": "codebase__code_embeddings",
        "TRACKING_TABLE": "codebase__cocoindex_tracking"
      }
    }
  }
}

Configuration and environment

Environment variables you will set for running the server are: - DATABASE_URL: PostgreSQL connection string - VOYAGE_API_KEY: API key for the Voyage embedding model - EMBEDDING_TABLE: Table name for code embeddings - TRACKING_TABLE: Table name for file tracking

Notes on usage patterns

- Use search_codebase to find code snippets that match natural language queries or code terms. The results are ranked by semantic similarity to your query. - Use get_files to obtain a complete list of files tracked in the codebase. - Use get_file_content with a specific filename to retrieve the full content of that file.

Security considerations

- Keep your DATABASE_URL and VOYAGE_API_KEY secure. Do not expose them in client-side code or logs. - Use network access controls to restrict who can reach port 8080 where the MCP server exposes its HTTP surface.

Troubleshooting

- If the server fails to start, verify that Docker is running, the environment variables are correctly set, and the PostgreSQL database is accessible from the host where you start the container. - Check the container logs for authentication errors with the database or embedding service and ensure the embedding table and tracking table exist in your database.

Available tools

search_codebase

Returns code snippets relevant to the query using semantic embeddings.

get_files

Lists all files tracked in the codebase.

get_file_content

Returns the full content of the specified file by filename.