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.

Choose the Right MCP Endpoint

Card Hedge has two separate Streamable HTTP MCP servers. Choose based on how you want to authenticate and pay:

Use Case	Endpoint	Authentication / Payment
Subscriber MCP (recommended)	https://api.cardhedger.com/mcp	X-API-Key; uses your Card Hedge API plan
Agent-payment MCP	https://api.cardhedger.com/mcp/agent/	No API key; paid tools use x402 pay-per-call
SSE (DEPRECATED)	https://api.cardhedger.com/mcp/sse	API key; existing legacy integrations only

Quick Start: API-Key MCP

1. Get a Card Hedge API key.
2. Add https://api.cardhedger.com/mcp to your client as a remote Streamable HTTP MCP server.
3. Configure X-API-Key: your-api-key as an HTTP header on the server connection.
4. Reconnect the server and confirm the client displays the Card Hedge tools.
5. Ask the agent a question such as Find the 2011 Topps Update Mike Trout rookie and show its PSA 10 price.

Client Setup

Claude Code

Add the remote HTTP server from a terminal, then verify the saved connection:

claude mcp add --transport http card-hedge   "https://api.cardhedger.com/mcp"   --header "X-API-Key: your-api-key-here"

claude mcp get card-hedge

OpenAI Codex (CLI, IDE, and App)

Codex stores MCP connections in config.toml. Use ~/.codex/config.toml for every project on your computer, or .codex/config.toml inside a trusted project for project-only access. The Codex CLI, IDE extension, and desktop app share this configuration on the same host.

Set the API key in the environment that launches Codex:

# macOS or Linux
export CARD_HEDGE_API_KEY="your-api-key-here"

# Windows PowerShell (current session)
$env:CARD_HEDGE_API_KEY="your-api-key-here"

Then add this server configuration:

[mcp_servers.card_hedge]
url = "https://api.cardhedger.com/mcp"
env_http_headers = { "X-API-Key" = "CARD_HEDGE_API_KEY" }

Restart the Codex app or IDE extension, or start a new Codex CLI session. Run codex mcp list in a terminal to confirm card_hedge is configured; in the Codex CLI, enter /mcp to confirm it is connected. Then ask Codex to Search for 2011 Topps Update Mike Trout and show the PSA 10 price.

Cursor

Add this to .cursor/mcp.json for one project or ~/.cursor/mcp.json for all projects, then replace the placeholder and restart the server from Cursor's MCP settings:

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

Claude and Claude Desktop Remote Connectors

Custom Python Agent

Install mcp and httpx, set CARD_HEDGE_API_KEY, and run this complete example:

import asyncio
import os

import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

MCP_URL = "https://api.cardhedger.com/mcp"


async def main():
    async with httpx.AsyncClient(
        headers={"X-API-Key": os.environ["CARD_HEDGE_API_KEY"]}
    ) as http_client:
        async with streamable_http_client(
            MCP_URL,
            http_client=http_client,
            terminate_on_close=False,
        ) as (read, write, get_session_id):
            async with ClientSession(read, write) as session:
                await session.initialize()

                tools = await session.list_tools()
                print([tool.name for tool in tools.tools])

                result = await session.call_tool(
                    "match_card",
                    arguments={
                        "query": "2011 Topps Update Mike Trout US175",
                        "category": "Baseball",
                    },
                )
                print(result.content[0].text)


asyncio.run(main())

Test with MCP Inspector

Run npx @modelcontextprotocol/inspector, select Streamable HTTP, enter https://api.cardhedger.com/mcp, and add X-API-Key under request headers. Connect, open the Tools tab, and call match_card.

Agent-Payment MCP (x402)

https://api.cardhedger.com/mcp/agent/ is a separate, stateless MCP server for autonomous agents that pay per call. The trailing slash is required by MCP clients that do not follow HTTP redirects. Do not send a Card Hedge API key to this endpoint.

• tools/list, agent_pricing_manifest, and agent_set_search are free.
• A paid tool first returns an x402 PaymentRequired tool result.
• An x402-aware MCP client signs the payment and retries the same tool call using request _meta["x402/payment"].
• The successful result includes the settlement receipt in response _meta["x402/payment-response"].

See the Agent API and x402 guide for prices, supported tools, wallet flow, and payment examples.

Legacy SSE via mcp-remote (Deprecated)

Do not use this configuration for a new integration. It is shown only for existing clients that cannot yet migrate. Prefer a client's native Streamable HTTP support and connect it directly to https://api.cardhedger.com/mcp.

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

Available 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 3.5M+ 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
get_card_fmv	Fair Market Value (FMV) for a card at a grade — smoothed valuation with confidence grade and explanation
get_fmv_by_cert	FMV by grader certificate number (cert → card → FMV in one call)
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"
"What's the FMV of a Charizard Base Set holo in PSA 9?"
"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.

Subscriber Authentication

These methods apply to the subscription server at /mcp. They do not apply to the x402 server at /mcp/agent/.

Method	How	When to Use
Header	X-API-Key: your-key	Preferred: Claude Code, Cursor, Inspector, custom agents

API-key clients must send the key on every MCP HTTP request. Do not put credentials in the URL: URLs may be stored in client configuration, browser history, proxy logs, or monitoring systems.

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

Troubleshooting

• Server connects but no tools appear: Confirm the URL ends in exactly /mcp, the transport is Streamable HTTP (not SSE), then reconnect or restart the MCP server in your client.
• "Could not find session" or 404 on tool calls: If the URL is /mcp/sse, this is the legacy transport's process-local session limitation; migrate to /mcp. If the URL is already /mcp, remove any saved Mcp-Session-Id behavior and reconnect; the stateless server does not issue a session ID.
• 401 authentication error: Complete the OAuth browser flow, or configure X-API-Key so the client sends it on every request. Do not append the key to the URL.
• A tool returns PaymentRequired: You connected to /mcp/agent/. Use an x402-aware client to pay and retry, or switch to /mcp with your API key.
• 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