# Connect Veritally as an MCP server

The Veritally MCP server lets an agent keep its **own** books: record what it
spends, check a budget before spending, and prove its ledger is intact — all in
its principal's tenant.

- **Endpoint:** `https://mcp.veritally.ai/mcp` (Streamable HTTP, JSON-RPC 2.0)
- **Auth:** your Veritally API key, configured at connector setup.
- **Tools:**
  | tool | read-only | use it to |
  |---|---|---|
  | `record_spend` | no | book token usage after doing work |
  | `record_payment` | no | book a card/wallet/merchant charge |
  | `check_budget` | yes | confirm a budget allows a spend, *before* spending |
  | `get_spend_summary` | yes | totals by agent/project/category for a period |
  | `verify_ledger` | yes | re-walk the hash chain and prove integrity |

A key with the **ingest** or **admin** role can use every tool. A public/demo
connection (no key) can use the three read-only tools; writes are refused.

## Claude (claude.ai custom connector)

1. Settings → Connectors → **Add custom connector**.
2. Name: `Veritally`. URL: `https://mcp.veritally.ai/mcp`.
3. Auth: **Bearer token** → paste your Veritally API key.
4. Save. In a chat, enable the Veritally connector. Ask: *"Check my research-agent
   budget, then record 120k input / 40k output tokens of gpt-4o against it."*

## Claude Code / Claude Desktop (`claude_desktop_config.json` or `.mcp.json`)

```json
{
  "mcpServers": {
    "veritally": {
      "type": "http",
      "url": "https://mcp.veritally.ai/mcp",
      "headers": { "Authorization": "Bearer vt_live_your_key" }
    }
  }
}
```

## ChatGPT (custom connector / developer mode)

Add a connector of type **MCP** pointing at `https://mcp.veritally.ai/mcp`, with
an `Authorization: Bearer <key>` header. ChatGPT surfaces the read-only tools for
lookups; grant write when you want the agent to book its own spend.

## Smoke-test with the MCP Inspector

```bash
npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP · URL: https://mcp.veritally.ai/mcp
# Header: Authorization: Bearer <key>  → Connect → List Tools → call verify_ledger
```

## Raw JSON-RPC (what the client sends)

```bash
curl -s https://mcp.veritally.ai/mcp \
  -H "Authorization: Bearer $VT_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"check_budget","arguments":{"scope":"agent","name":"research-agent"}}}'
```