Configuring AI Tools

Configuring AI Tools

This chapter shows how to connect various MCP clients to a running pp-mcp instance. See Installation first to get the server running.

Transports pp-mcp supports

• streamable-http (default) / sse — a resident HTTP server, reachable at http://<host>:<port>/mcp (/sse if MCP_TRANSPORT=sse). Useful when pp-mcp runs continuously somewhere (e.g. a NAS or a background service) and multiple clients/sessions connect to it over the network. Supports optional bearer-token auth via MCP_AUTH_TOKEN.
• stdio — no resident server at all. The MCP client launches pp-mcp itself as a subprocess for each session and talks MCP over stdin/stdout. No port, no bearer token (there's no HTTP layer to protect), nothing to keep running in the background. The right choice if you don't already run pp-mcp continuously.

Pick whichever matches how you actually run pp-mcp (see Installation).

Claude Code (CLI)

HTTP transport, via the CLI:

claude mcp add --transport http pp-mcp http://localhost:8080/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Omit --header if MCP_AUTH_TOKEN is empty. This writes to ~/.claude.json (user scope); add --scope project to write to .mcp.json in the current project instead. Equivalent manual config:

{
  "mcpServers": {
    "pp-mcp": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_AUTH_TOKEN>"
      }
    }
  }
}

Drop the headers block entirely if no auth token is configured. For stdio, use claude mcp add with a command instead of --transport http (same shape as the Claude Desktop stdio config below).

Claude Desktop

Claude Desktop only launches local stdio MCP servers directly — it cannot connect to a remote streamable-http server on its own.

stdio (pp-mcp launched by Claude Desktop)

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pp-mcp": {
      "command": "python3",
      "args": ["-m", "src.main"],
      "env": {
        "PYTHONPATH": "/path/to/pp-mcp",
        "MCP_TRANSPORT": "stdio",
        "PP_FILE_PATH": "/path/to/file.portfolio"
      }
    }
  }
}

A few details that matter here:

• Use -m src.main (module invocation), not src/main.py as a plain script.
• PYTHONPATH must point at the repo root so the src package resolves. Claude Desktop does not honor a cwd key in this config — confirmed: adding one is silently ignored — so PYTHONPATH is the only reliable fix. Without it: ModuleNotFoundError: No module named 'src'.
• command must be the Python interpreter that actually has requirements.txt installed (e.g. a venv's python3) — Claude Desktop does not inherit your shell's virtualenv.
• For multi-source, set PP_PORTFOLIOS_CONFIG in env instead of PP_FILE_PATH.

Alternative: uv instead of python3/PYTHONPATH. If you manage the Python install/dependencies with uv, its --directory flag changes into the repo directory before running the command — so the src package resolves regardless of whether the client honors cwd, no PYTHONPATH workaround needed:

uv python install 3.11
cd /path/to/pp-mcp && uv venv --python 3.11 && uv pip install -r requirements.txt

{
  "mcpServers": {
    "pp-mcp": {
      "command": "/absolute/path/to/uv",
      "args": [
        "--directory", "/path/to/pp-mcp",
        "run", "--no-project", "python", "-m", "src.main"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "PP_FILE_PATH": "/path/to/file.portfolio"
      }
    }
  }
}

Use the absolute path reported by command -v uv — GUI apps like Claude Desktop may not inherit the shell's PATH. --no-project keeps requirements.txt/uv pip install as the dependency source, so an unrelated parent pyproject.toml isn't picked up by mistake.

streamable-http (pp-mcp running continuously elsewhere, e.g. a NAS)

Bridge it through a stdio-to-HTTP adapter such as mcp-remote:

{
  "mcpServers": {
    "pp-mcp": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "http://localhost:8080/mcp",
        "--header", "Authorization: Bearer <MCP_AUTH_TOKEN>"
      ]
    }
  }
}

Other MCP-capable clients

pp-mcp is a standard MCP server, not Claude-specific — any MCP-compatible client or AI assistant can use it:

• Via stdio: launch it directly, same shape as the Claude Desktop stdio config above (command/args/env).
• Via streamable-http: point the client at http://<host>:<port>/mcp and, if MCP_AUTH_TOKEN is set, add an Authorization: Bearer <MCP_AUTH_TOKEN> HTTP header. Check your client's own docs for how it configures remote/HTTP MCP servers — some clients (like Claude Desktop) only support local stdio servers directly and need a bridge like mcp-remote, while others (IDE integrations, agent frameworks, other LLM chat apps) support remote MCP servers natively.

Troubleshooting

Symptom	Likely cause
ModuleNotFoundError: No module named 'src'	Missing/wrong PYTHONPATH in a stdio config, or running python src/main.py instead of python -m src.main.
Client can't find/start the command at all	command isn't an absolute path, or the GUI app doesn't inherit your shell's PATH/virtualenv — use an absolute interpreter path.
401 unauthorized over HTTP	Missing or wrong Authorization: Bearer <token> header — check MCP_AUTH_TOKEN matches on both sides.
Connection refused / timeout over HTTP	Server not running, wrong host/port, or MCP_SERVER_HOST bound to an interface the client can't reach (see Installation). Verify with the ping tool or the TCP healthcheck first.
Tool calls succeed but return {"status": "error", ...}	Not a connection problem — the server is reachable and the error message describes the actual issue (e.g. wrong source/security name).

---

← Installation · AI Examples →