MCP Integration

Connect AI agents to Card Hedge data using the Model Context Protocol.

What is MCP?

The Model Context Protocol lets AI assistants like Claude, GPTs, and LangChain agents call API tools directly during conversations. Instead of copy-pasting data, the AI can search cards, look up prices, and analyze markets on its own.

Transports

We support two MCP transports. Use whichever your client supports:

Transport	Endpoint	Best For
Streamable HTTP	`https://api.cardhedger.com/mcp`	Claude Desktop, Claude Code, Claude.ai, modern MCP clients
SSE (Server-Sent Events)	`https://api.cardhedger.com/mcp/sse`	mcp-remote, Cursor, Windsurf, older MCP clients

Which should I use? If your client supports "type": "url" in its config, use Streamable HTTP (/mcp). If your client requires mcp-remote or uses SSE, use the SSE endpoint (/mcp/sse).

Setup Guides

Claude Desktop

Claude Desktop supports Streamable HTTP natively. Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "card-hedge": {
      "type": "url",
      "url": "https://api.cardhedger.com/mcp",
      "headers": {
        "X-API-Key": "your-api-key-here"
      }
    }
  }
}

Claude Code

Add to your .claude/settings.json or run claude mcp add:

{
  "mcpServers": {
    "card-hedge": {
      "type": "url",
      "url": "https://api.cardhedger.com/mcp",
      "headers": {
        "X-API-Key": "your-api-key-here"
      }
    }
  }
}

Claude.ai (Web)

In Claude.ai, go to Settings → MCP Servers → Add Server. Enter the URL with your API key as a query parameter (Claude.ai does not support custom headers):

https://api.cardhedger.com/mcp?api_key=your-api-key-here

Cursor / Windsurf / mcp-remote

Clients that use mcp-remote or require SSE transport should use the /mcp/sse endpoint. Add to your MCP config:

{
  "mcpServers": {
    "card-hedge": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.cardhedger.com/mcp/sse",
        "--header", "X-API-Key:${API_KEY}"
      ]
    }
  }
}

Note: Replace ${API_KEY} with your actual API key, or set it as an environment variable. If you see PROGRA~1 path errors on Windows, ensure Node.js is on your PATH without spaces.

Custom Agents (Python)

For custom AI agents using the MCP SDK, connect via either transport:

# Streamable HTTP (recommended)
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client(
    "https://api.cardhedger.com/mcp",
    headers={"X-API-Key": "your-api-key-here"}
) as (read, write, session_id):
    # Use read/write streams with your MCP client
    pass

# SSE transport
from mcp.client.sse import sse_client

async with sse_client(
    "https://api.cardhedger.com/mcp/sse",
    headers={"X-API-Key": "your-api-key-here"}
) as (read, write):
    # Use read/write streams with your MCP client
    pass

Other MCP Clients

Any MCP-compatible client can connect. Pass your API key via the X-API-Key header, or as an ?api_key= query parameter if headers aren't supported.

Available Tools

Workflow tip: Most pricing tools require a card_id. Use match_card or search_cards first to find the card, then pass the card_id to pricing tools.

Tool	Description
match_card	AI-powered card matching from natural language descriptions. Use this first to get a card_id.
search_cards	Text search across 2.7M+ cards
search_sets	Search for card sets by name
search_cards_sorted	Search with custom sorting options
get_top_movers	Cards with biggest recent price gains
get_card_details	Full card details by card_id
get_prices_by_cert	Price lookup by certificate number (PSA, BGS, etc.)
get_details_by_certs	Batch certificate lookup (up to 100)
get_price_history	Historical price data for a card and grade
get_all_prices	Latest prices across all grades for a card
get_comps	Comparable sale prices with anomaly filtering
estimate_price	AI-driven price estimation with confidence intervals
get_total_sales_by_player	Total sales count by player/character (last N days)

Example Conversation

Once connected, you can ask your AI assistant things like:

"What's a PSA 10 2011 Topps Update Mike Trout rookie worth?"
"Show me the top movers in baseball cards today"
"Look up PSA certificate 50000000"
"Compare recent sales for Ken Griffey Jr 1989 Upper Deck PSA 9"

The AI will automatically call the right tools in the right order to answer your question.

Authentication

Both MCP endpoints use the same API key as the REST API. You can authenticate in two ways:

Method	How	When to Use
Header	`X-API-Key: your-key`	Claude Desktop, Claude Code, mcp-remote, custom agents
Query param	`?api_key=your-key`	Claude.ai web connector (no custom header support)

Don't have a key yet? Get an API key here.

Troubleshooting

"Could not find session" or 404 on tool calls: You may be using the wrong transport. If your client uses mcp-remote, switch to the SSE endpoint (/mcp/sse). If your client supports "type": "url", use Streamable HTTP (/mcp).
401 "Missing API key" on tool calls: Your API key is reaching the MCP server but not being forwarded to tool calls. Make sure you pass it via the X-API-Key header (not Authorization), or use the ?api_key= query parameter.
PROGRA~1 path errors (Windows): This is a Node.js path issue with mcp-remote. Ensure Node.js is installed to a path without spaces, or use the full path to npx.
Tools load but calls fail: Check that your API key is active and has not been revoked. Try a direct REST API call to verify: curl -H "X-API-Key: your-key" https://api.cardhedger.com/v1/cards/top-movers