MCP connector

Grail speaks the Model Context Protocol, so Claude, Cursor, Codex and any MCP-capable client can call our sold-price engine as tools. Same grail_… key you already have — no glue code, no separate account.

Get a key REST API docs

Authentication

Set GRAIL_MCP_API_KEY to any active Grail key. The connector authenticates it against the same store that guards /v1/*, so keys minted in the dashboard work here immediately. No key is refused in production (fail-closed); anonymous use is allowed only in dev/test.

Tools

search_sold

Recent eBay sold listings for a query. Returns a verified price summary (median / mean / min / max / p25 / p75) plus rows. Best-Offer amounts are unverified and excluded.

card_research

Grade-by-grade read on one card (raw / PSA 9 / PSA 10) with honest confidence tiers — nulls + a reason when the window is too short to claim a trend.

shipping_rates

Observed shipping amounts for a keyword from our corpus, plus a clearly-labelled estimate for landed cost.

usage

Current-period API usage for the authenticated key — plan, quotas, remaining. Never debits.

Hosted connector (recommended)

Skip the local install. Grail runs a hosted streamable-HTTP connector at https://grail.solutions/mcp. Point any remote MCP client at it with your key in the Authorization header — no Python, no file editing.

# Hosted connector (streamable-HTTP) — no local install, no Python.
# Base URL:
https://grail.solutions/mcp

# Claude Code
claude mcp add --transport http grail https://grail.solutions/mcp \
  --header "Authorization: Bearer gk_live_your_key"

# Codex CLI  (~/.codex/config.toml)
[mcp_servers.grail]
url = "https://grail.solutions/mcp"
http_headers = { Authorization = "Bearer gk_live_your_key" }

Anonymous use is refused in production (fail-closed). OAuth so clients can connect without pasting a key is next.

Claude Desktop (local)

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "grail": {
      "command": "python",
      "args": ["-m", "comps_api.mcp_server"],
      "cwd": "/path/to/Grail/backend",
      "env": {
        "GRAIL_MCP_API_KEY": "grail_your_key",
        "GRAIL_ENV": "prod"
      }
    }
  }
}

Cursor

Add a server entry under mcpServers:

{
  "mcpServers": {
    "grail": {
      "command": "python",
      "args": ["-m", "comps_api.mcp_server"],
      "env": { "GRAIL_MCP_API_KEY": "grail_your_key" }
    }
  }
}

Streamable HTTP

Prefer HTTP over stdio? Run the connector in HTTP mode and point any remote MCP client at it:

# streamable-HTTP transport instead of stdio
GRAIL_MCP_TRANSPORT=streamable-http \
GRAIL_MCP_API_KEY=grail_your_key \
python -m comps_api.mcp_server
# serves MCP at http://127.0.0.1:8000/mcp

Try it

“What did a PSA 10 Mew ex 151 sell for recently?”
“Is $380 a good price for a raw Base Set Charizard?”
“Show me the grade spread for Hidden Fates Charizard-GX.”

Every answer is grounded in real sold transactions — Grail returns honest confidence, and never fabricates a trend from too little data.