# How to Configure MCP Server for Claude Code Integration: A Complete Setup Guide

> Learn to configure MCP server for Claude Code integration in Code-Graph-RAG. Connect Claude to your codebase using environment variables and graph-powered tools for seamless natural language interaction.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: how-to-guide
- Published: 2026-08-20

---

**The MCP server in Code-Graph-RAG bridges Claude Code with your codebase through natural language by reading environment variables like `TARGET_REPO_PATH` and exposing graph-powered tools over stdio or HTTP transport.**

The **Model Context Protocol (MCP)** server in the [vitali87/code-graph-rag](https://github.com/vitali87/code-graph-rag) repository lets Claude Code query, search, and edit codebases without manual file navigation. This guide walks through configuring that server, from environment setup to tool registration, based on the actual implementation in [`codebase_rag/mcp/server.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py).

## What the MCP Server Does

When you configure MCP server for Claude Code integration, you're enabling a **transport-agnostic bridge** between Claude's natural language interface and a rich code graph stored in Memgraph. The server performs three core operations on startup:

1. **Resolves the target repository** from environment variables or falls back to the current working directory
2. **Builds or updates a semantic code graph** with AST-level detail in Memgraph
3. **Registers MCP tools** (`semantic_search`, `write_file`, `list_projects`, etc.) that Claude can invoke

The implementation handles incoming MCP requests through `MCPHandlerType` handlers and returns structured `MCPResultType` responses, making the entire codebase queryable through conversational commands.

## Environment Variables for MCP Server Configuration

The server reads configuration at startup from environment variables defined in [`codebase_rag/constants/mcp.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants/mcp.py) and processed through [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py). These control both the repository scope and LLM backend.

| Variable | Purpose | Default |
|----------|---------|---------|
| `TARGET_REPO_PATH` | Absolute path to the project you want Claude to access | Current working directory (`.`) |
| `CYPHER_PROVIDER` | LLM provider for graph queries (`openai`, `google`, etc.) | Provider-specific |
| `CYPHER_MODEL` | Specific model name for embeddings and generation | Provider-specific |
| `CYPHER_API_KEY` | API key for the selected provider (never store in repo) | None |

The resolution logic in [`codebase_rag/mcp/server.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py) (line 44) prioritizes environment variables over config file defaults:

```python
repo_path = os.environ.get(cs.MCPEnvVar.TARGET_REPO_PATH) or settings.TARGET_REPO_PATH

```

This means you can override `TARGET_REPO_PATH` per session without modifying [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py), where the default is hardcoded as `TARGET_REPO_PATH = "."`.

## Method 1: Installing via pip and Adding to Claude Code

For users who installed `code-graph-rag` through pip, register the MCP server with Claude Code using the `claude mcp add` command:

```bash
claude mcp add --transport stdio code-graph-rag \
  --env TARGET_REPO_PATH=/absolute/path/to/your/project \
  --env CYPHER_PROVIDER=openai \
  --env CYPHER_MODEL=gpt-4o \
  --env CYPHER_API_KEY=your-api-key \
  -- code-graph-rag mcp-server

```

**Key flags explained:**

- `--transport stdio` – Required for Claude Code CLI integration (default; HTTP available for other clients)
- `--env` – Injects environment variables into the server process
- `code-graph-rag mcp-server` – The entry point command that launches [`codebase_rag/mcp/server.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py)

## Method 2: Running From Source with uv

When developing or running directly from the repository, use `uv run` to execute the server without installation:

```bash
claude mcp add --transport stdio code-graph-rag \
  --env TARGET_REPO_PATH=/absolute/path/to/your/project \
  --env CYPHER_PROVIDER=openai \
  --env CYPHER_MODEL=gpt-4o \
  --env CYPHER_API_KEY=your-api-key \
  -- uv run --directory /path/to/code-graph-rag code-graph-rag mcp-server

```

The `--directory` flag ensures uv finds the project root, while the trailing `--` separates Claude's arguments from the server command.

## Method 3: Using the Current Directory Dynamically

To automatically target whichever directory you launch Claude from:

```bash
cd /path/to/your/project
claude mcp add --transport stdio code-graph-rag \
  --env TARGET_REPO_PATH="$(pwd)" \
  --env CYPHER_PROVIDER=google \
  --env CYPHER_MODEL=gemini-1.5-flash \
  --env CYPHER_API_KEY=your-google-api-key \
  -- uv run --directory /absolute/path/to/code-graph-rag code-graph-rag mcp-server

```

This pattern is useful for frequently switching between multiple repositories without reconfiguring.

## Verifying the Integration: Example MCP Request

Once configured, Claude Code can invoke registered tools. The tool descriptions in [`codebase_rag/tools/tool_descriptions.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/tools/tool_descriptions.py) populate the available commands. A typical request flows like this:

```json
{
  "tool": "semantic_search",
  "params": {
    "question": "Find all functions that send an email"
  }
}

```

The `MCPToolsRegistry` routes this to the appropriate handler, queries the Memgraph code graph, and returns ranked function matches with similarity scores and source locations.

## Core Implementation Files

Understanding these files helps debug configuration issues:

| File | Role |
|------|------|
| [`codebase_rag/mcp/server.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py) | Main server loop, environment resolution, request routing via `MCPHandlerType` |
| [`codebase_rag/constants/mcp.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants/mcp.py) | String constants for environment variable names (e.g., `TARGET_REPO_PATH` key) |
| [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py) | Pydantic `Settings` class with defaults; loaded when env vars are absent |
| [`codebase_rag/tools/tool_descriptions.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/tools/tool_descriptions.py) | Maps tool names to human-readable descriptions for the MCP tool table |

## Transport Options: stdio vs HTTP

The server implementation in [`codebase_rag/mcp/server.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py) is **transport-agnostic**. While Claude Code requires `--transport stdio` for subprocess communication, you can launch with HTTP for other MCP clients:

```bash
code-graph-rag mcp-server --transport http --port 8080

```

This flexibility comes from separating the protocol handler from transport layer in the server architecture.

## Summary

- **Set `TARGET_REPO_PATH`** to point Claude at your target codebase; it resolves via environment variable first, then config file, then working directory
- **Use `claude mcp add`** with `--transport stdio` for CLI integration, passing provider credentials via `--env` flags
- **Run from source** with `uv run --directory <repo> code-graph-rag mcp-server` when developing
- **Reference [`codebase_rag/constants/mcp.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/constants/mcp.py)** for supported environment variable names
- **Leverage the full tool suite** registered from [`codebase_rag/tools/tool_descriptions.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/tools/tool_descriptions.py) for semantic search, file editing, and project exploration

## Frequently Asked Questions

### What happens if I don't set TARGET_REPO_PATH?

The server falls back to `settings.TARGET_REPO_PATH` from [`codebase_rag/config.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/config.py) (defaults to `"."`), which then resolves to the directory where Claude Code was launched. This works for single-project workflows but explicit configuration prevents accidental targeting.

### Can I use different LLM providers for different projects?

Yes. The `CYPHER_PROVIDER`, `CYPHER_MODEL`, and `CYPHER_API_KEY` variables are read fresh on each server startup. Create separate `claude mcp add` registrations with different environment variable sets, or switch providers by modifying the env vars before launching.

### Why does Claude Code require stdio transport?

stdio transport creates a direct subprocess pipe between Claude Code and the MCP server, enabling real-time bidirectional communication without network overhead. The server's transport-agnostic design in [`codebase_rag/mcp/server.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/server.py) supports this while allowing HTTP for browser-based or remote clients.

### Where are the tool descriptions defined that Claude sees?

All tool metadata lives in [`codebase_rag/tools/tool_descriptions.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/tools/tool_descriptions.py). The `MCPToolsRegistry` consumes this file to build the capability table exposed to MCP clients, mapping each tool name to its description, parameters, and return schema.