MCP Protocol

Premium Only

Connect Claude Desktop, ChatGPT, and any MCP-compatible AI client directly to CardMind via the Model Context Protocol. Ask your AI assistant to look up card prices, analyze card market data, and track market signals — all in natural language.

Premium API key required

MCP access requires a Premium CardMind subscription. Free-tier keys receive 403 PREMIUM_REQUIRED when connecting. Upgrade at cardmind.app/settings/api.

Technical Details

MCP Endpoint	https://api.cardmind.app/mcp
Transport	HTTP Streamable (WebStandard), stateless mode
Authentication	Authorization: Bearer cm_live_YOUR_KEY
Protocol version	MCP 2025-03-26
Session state	None — each request is fully independent

Claude Desktop Setup

Add the following block to your claude_desktop_config.json file. On macOS the config lives at ~/Library/Application Support/Claude/claude_desktop_config.json.

{
  "mcpServers": {
    "cardmind": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.cardmind.app/mcp",
        "--header",
        "Authorization: Bearer cm_live_YOUR_KEY"
      ]
    }
  }
}

Replace cm_live_YOUR_KEY with your actual Premium API key. Requires Node.js installed — the mcp-remote package bridges Claude Desktop's stdio transport to CardMind's HTTP transport. Restart Claude Desktop after saving the config.

For MCP clients that support Streamable HTTP transport natively

Future Claude Desktop versions, ChatGPT, and other HTTP-native clients can connect directly — no mcp-remote bridge needed:

Endpoint: https://api.cardmind.app/mcp

Header: Authorization: Bearer cm_live_YOUR_KEY

Verify the connection

After restarting, open a new conversation in Claude Desktop and type:

“Use CardMind to search for Lightning Bolt and tell me its current price.”

Claude will invoke the search_cards tool and display live price data from CardMind.

ChatGPT and Other MCP Clients

Any MCP-compatible client can connect to the CardMind endpoint. Configure it with:

Endpoint URL: https://api.cardmind.app/mcp
Auth header: Authorization: Bearer cm_live_YOUR_KEY
Transport: HTTP (not stdio)

See your MCP client's documentation for exact configuration steps. The CardMind endpoint is stateless — no persistent session is required.

Available MCP Tools

The CardMind MCP server exposes 5 tools. All tools are registered in lib/mcp-tools.ts and require a Premium API key.

search_cards

Search Magic: The Gathering cards by name with optional set and format filters. Returns up to 100 matching cards with price data.

Parameter	Type	Required	Description
q	string	required	Search term — matches card name
set	string	optional	Filter by set code (e.g. "ltr", "lea")
format	string	optional	Filter by legality format (e.g. "standard", "modern", "legacy")
limit	number (1–100)	optional	Maximum number of results to return. Default: 20

get_card

Get a single Magic: The Gathering card by its Scryfall UUID, including full metadata and 30-day price history.

Parameter	Type	Required	Description
scryfall_id	string (UUID)	required	Scryfall card UUID (e.g. "e3285e6b-3e79-4d7c-bf96-d920f973b122")

get_price_movers

Get the top gaining and losing cards over a configurable time period. Returns separate "gainers" and "losers" arrays ranked by price change percentage.

Parameter	Type	Required	Description
period	"1d" \| "7d" \| "30d" \| "all"	optional	Time window for price comparison. Default: "7d"
limit	number (1–100)	optional	Cards to return in each list. Default: 10

get_signals

Retrieve recent market signals — algorithmically detected price movements and market events — optionally filtered by signal type.

Parameter	Type	Required	Description
type	string	optional	Filter by signal type (e.g. "price_spike", "price_drop", "buy_opportunity"). Omit to return all types
limit	number (1–100)	optional	Maximum signals to return. Default: 20

analyze_card

Use Claude Haiku AI to analyze a card for competitive play potential and market value. Responses are cached for 6 hours per card.

Parameter	Type	Required	Description
scryfall_id	string (UUID)	required	Scryfall card UUID to analyze

Error Handling

When a tool call fails (database error, card not found, AI unavailable), the MCP server returns the result with isError: true rather than throwing an exception. The error message is surfaced as a text content block so your AI client can relay it naturally.

// Tool error response example
{
  "content": [
    { "type": "text", "text": "Card not found" }
  ],
  "isError": true
}