Configuration Overview

The Code Pathfinder MCP server supports multiple configuration options to customize its behavior for different use cases.

Command-Line Flags

Basic Usage

pathfinder serve [flags]

Available Flags

Examples

Basic stdio Mode (Default)

$ pathfinder serve --project /path/to/project

This starts the MCP server in stdio mode, suitable for local AI assistants like Claude Code, Codex, OpenCode, and Windsurf.

HTTP Mode for Remote Access

$ pathfinder serve --project /path/to/project --http --address :8080

Starts an HTTP server on port 8080 that accepts MCP requests over HTTP.

Custom Python Version

$ pathfinder serve --project /path/to/project --python-version 3.11

Forces the server to index using Python 3.11 semantics instead of auto-detection.

Custom Port

$ pathfinder serve --project /path/to/project --http --address localhost:9000

Runs HTTP server on port 9000 instead of default 8080.

AI Assistant Configuration

Claude Code Configuration

Edit your Claude Code MCP settings file:

{
  "mcpServers": {
"code-pathfinder": {
  "command": "pathfinder",
  "args": ["serve", "--project", "/absolute/path/to/project"]
}
  }
}

Codex Configuration

Add to your Codex MCP configuration (TOML format):

[mcpServers.code-pathfinder]
command = "pathfinder"
args = ["serve", "--project", "/absolute/path/to/project"]

OpenCode / Windsurf Configuration

Configure in your AI assistant's MCP settings:

{
  "mcpServers": {
"code-pathfinder": {
  "command": "pathfinder",
  "args": ["serve", "--project", "/absolute/path/to/project"]
}
  }
}

Multiple Projects

Configure multiple projects as separate MCP servers:

{
  "mcpServers": {
"backend-api": {
  "command": "pathfinder",
  "args": ["serve", "--project", "/Users/you/code/backend"]
},
"frontend-web": {
  "command": "pathfinder",
  "args": ["serve", "--project", "/Users/you/code/frontend"]
},
"shared-lib": {
  "command": "pathfinder",
  "args": ["serve", "--project", "/Users/you/code/shared"]
}
  }
}

Your AI assistant will show all three as available MCP servers. You can query each independently, or prompt explicitly to strategically query flow across projects. Let your AI assistant drive code navigation to create a map-like understanding of how your microservices interact, trace data flows between frontend and backend, or analyze dependencies across your entire system architecture.

Python Version Override

Specify exact Python version when auto-detection fails:

{
  "mcpServers": {
"code-pathfinder": {
  "command": "pathfinder",
  "args": [
    "serve",
    "--project", "/path/to/project",
    "--python-version", "3.11"
  ]
}
  }
}

Using Local Binary

If pathfinder isn't in your PATH:

{
  "mcpServers": {
"code-pathfinder": {
  "command": "/absolute/path/to/pathfinder",
  "args": ["serve", "--project", "/path/to/project"]
}
  }
}

HTTP Transport Configuration

Starting HTTP Server

$ pathfinder serve --project /path/to/project --http --address :8080

The server will listen on http://localhost:8080 and accept MCP requests over HTTP.

HTTP Endpoints

Health Check

Returns server status and readiness:

{
  "status": "ready",
  "version": "0.1.0-poc",
  "indexed_at": "2026-01-10T10:30:00Z"
}

MCP JSON-RPC Endpoint

Accepts MCP JSON-RPC 2.0 requests:

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