# PCH MCP Server

Drop-in MCP server for [PathCourse Health (PCH)](https://pathcoursehealth.com) — cheaper LLM inference, USDC-based agent payments, and agent identity / reputation lookup. Works in Claude Desktop, Cursor, Cline, Continue.dev, and Zed.

**14 tools.** 7 free (no API key needed) and 7 authenticated. Includes a unique flow that lets you buy a PCH API key from inside Claude Desktop using USDC — no signup form, no email verification.

## Install

### Claude Desktop, Cursor, Cline, Continue.dev, Zed (npm)

Add to your client's MCP config:

```json
{
  "mcpServers": {
    "pch": {
      "command": "npx",
      "args": ["-y", "@pathcourse/mcp-server"],
      "env": {
        "PCH_API_KEY": "pch_prod_b_..."
      }
    }
  }
}
```

If you don't have a PCH API key yet, omit the `env` block. Many tools work without authentication; you can obtain a key via the `pch_provision` tool.

Per-client install instructions:
- [Claude Desktop](docs/install-claude-desktop.md)
- [Cursor](docs/install-cursor.md)
- [Cline (VS Code)](docs/install-cline.md)
- [Continue.dev](docs/install-continue.md)
- [Zed](docs/install-zed.md)

### Python clients (PyPI)

```bash
uvx pch-mcp-server
# or
pip install pch-mcp-server
```

## Tools

### Free (no API key)

| Tool | What it does |
|---|---|
| `pch_models` | List all PCH models with rates and tier requirements |
| `pch_estimate` | Estimate cost of an inference request before running it |
| `pch_status` | Gateway health and service status |
| `pch_provision` | Get USDC payment instructions to obtain an API key |
| `pch_pay` | Submit USDC payment proof; returns API key + first inference |
| `pch_lookup_agent_identity` | Lookup an agent's ERC-8004 identity record |
| `pch_get_path_score` | Look up an agent's Path Score (0-1000) |
| `pch_get_agent_history` | 12-month trend of an agent's score components |
| `pch_verify_certification` | Verify a PCH-issued certification |
| `pch_compare_costs` | Compare PCH model cost vs GPT-4o, Claude Sonnet, Claude Haiku |

### Authenticated (PCH_API_KEY required)

| Tool | What it does |
|---|---|
| `pch_inference` | Run LLM inference on a PCH model |
| `pch_balance` | Check remaining USDC balance and current tier |
| `pch_check_agent_reputation` | Deeper reputation lookup ($0.001 USDC per query) |
| `pch_my_account` | Self-service balance + identity + recent activity |

## Configuration

| Env var | Default | Notes |
|---|---|---|
| `PCH_API_KEY` | (none) | Required for authenticated tools. Format: `pch_prod_b_...` |
| `PCH_GATEWAY_URL` | `https://gateway.pathcoursehealth.com` | Override for staging or local dev |

## Security

**Never commit `PCH_API_KEY` to a public repo.** The wrapper logs a warning at startup if it detects a key that looks like a real production key being passed through env. If you accidentally exposed your key, rotate it via PCH support.

## License

MIT

## Source

This wrapper is open source: [pathcourse-health/pch-mcp-server](https://github.com/pathcourse-health/pch-mcp-server)

The upstream PCH MCP server lives in the (private) `pch-platform-gateway` repo.