MCP Client Setup

Pathfinder supports both the modern Streamable HTTP transport (/mcp) and the legacy SSE transport (/sse). OAuth authentication is automatic — no user accounts needed; clients register dynamically.

Transport Choices

Two endpoints ship in every Pathfinder instance. Pick the one your client supports:

Streamable HTTP (/mcp) — recommended for modern clients (Claude Code, Cursor HTTP mode, OpenCode).
SSE (/sse + /messages) — legacy transport; needed for the claude.ai web connector and older MCP clients.

Both transports share the same tools, sessions, and OAuth flow. Clients without a bearer token pass through; invalid bearers are rejected with 401.

Client Configurations

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

Claude Desktop uses its own config file with mcpServers as the top-level key.

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

Claude Code

~/.claude/mcp.json

Claude Code uses a separate config file with mcp-servers as the key.

{
  "mcp-servers": {
    "docs": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

Claude.ai (Web Connector)

Settings → Connectors → Add custom connector

claude.ai uses the legacy SSE transport. Paste your Pathfinder URL into the custom connector dialog, then click Authenticate — the OAuth handshake runs automatically and the connector is approved anonymously.

# Streamable HTTP (newer clients)
URL: https://your-pathfinder-host/mcp

# SSE (claude.ai and older clients)
URL: https://your-pathfinder-host/sse

Cursor

.cursor/mcp.json

Place this in your project root. Cursor picks it up automatically.

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

OpenAI Codex

codex CLI --mcp-config

Codex supports MCP servers via the --mcp-config flag or a config file. Pass a JSON file with the server definition:

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

VS Code (Continue)

~/.continue/config.json

Add Pathfinder to the mcpServers section of your Continue config:

{
  "mcpServers": [
    {
      "name": "docs",
      "transport": {
        "type": "http",
        "url": "http://localhost:3001/mcp"
      }
    }
  ]
}

Generic (Streamable HTTP)

Any MCP-compatible client

Pathfinder exposes a single Streamable HTTP endpoint. Any MCP client that supports this transport can connect with:

# Endpoint
URL:       http://localhost:3001/mcp
Transport: Streamable HTTP
Method:    POST

Remote Servers

For deployed Pathfinder instances, replace localhost:3001 with your server's URL:

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "https://docs.example.com/mcp"
    }
  }
}

Pathfinder handles session management automatically. Each MCP connection gets its own session with independent state (working directory, workspace, etc.).

Verifying the Connection

Once connected, your agent should see Pathfinder's tools in its available tools list. The exact tools depend on your configuration — typically a combination of search and bash tools.

Try asking your agent to run a simple command like find / -name "*.md" | head -5 to verify the bash tool is working, or ask a question about your docs to test semantic search.

Known Concerns

SSE Parsing Bugs in Some MCP Clients

Some MCP clients have bugs handling SSE-formatted responses from Streamable HTTP endpoints. This can cause initialization failures, connection drops, or cryptic errors when connecting to Pathfinder's /mcp endpoint.

The most notable example is OpenAI Codex CLI, which uses the rmcp Rust SDK internally. That SDK's SSE parser does not correctly handle the text/event-stream content type that MCP servers typically return for single-message exchanges over Streamable HTTP.

Pathfinder's Mitigation

Pathfinder enables enableJsonResponse: true on its Streamable HTTP transport. This causes the server to return Content-Type: application/json instead of SSE-wrapped responses for single-message exchanges (i.e., requests where the server sends exactly one response and does not need to stream). This is fully compliant with the MCP specification, which states that servers MAY return either format for non-streaming responses.

This setting works around the client-side bugs transparently — no configuration needed on your end.

stdio Bridge Workaround

If you still encounter connection issues with a particular client, you can use mcp-remote as a stdio bridge. This converts the HTTP transport into a local stdio pipe, which every MCP client supports reliably:

# Codex CLI — ~/.codex/config.toml

[mcp_servers.pathfinder]
command = "npx"
args = ["mcp-remote@latest", "--http", "--allow-http", "https://mcp.copilotkit.ai/mcp"]

Replace the URL with your own Pathfinder instance's /mcp endpoint. The --http flag tells mcp-remote to use Streamable HTTP (not SSE), and --allow-http permits non-TLS connections if you're running locally.