TCGVaultHQ MCP Server

The TCGVaultHQ MCP (Model Context Protocol) server provides programmatic access to Pokemon card data, prices, and market analytics. Use it to build trading bots, price trackers, collection tools, or integrate with AI assistants like Claude and ChatGPT.

Getting Started

1. Create an API Key

1. Sign in to your TCGVaultHQ account
2. Navigate to Tools > API Keys or go directly to /dashboard/api-keys
3. Click Create New Key
4. Give your key a descriptive name (e.g., "My Trading Bot", "Price Tracker")
5. Important: Copy your API key immediately - it will only be shown once!

Your API key looks like: tcgv_live_a1b2c3d4e5f6...

2. Make Your First Request

The MCP server endpoint is:

POST https://tcgvaulthq.com/api/mcp

Include your API key in the X-API-Key header:

curl -X POST https://tcgvaulthq.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tcgv_live_your_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_cards",
      "arguments": {
        "query": "Charizard"
      }
    }
  }'

Authentication

All requests require an API key passed in the X-API-Key header.

Rate Limits:

• 100 requests per minute per API key
• Exceeding the limit returns HTTP 429 with X-RateLimit-Reset header

Error Responses:

Code	HTTP Status	Meaning
-32001	401	Invalid or missing API key
-32002	429	Rate limit exceeded
-32003	400	Card not found
-32004	400	Invalid parameters
-32601	404	Method/tool not found

Available Tools

Card Lookup

search_cards

Search for Pokemon cards by name, set, rarity, or type.

Parameters:

Name	Type	Required	Description
query	string	Yes	Card name to search for
setName	string	No	Filter by set name
rarity	string	No	Filter by rarity (e.g., "Rare Holo", "Ultra Rare")
type	string	No	Filter by Pokemon type (e.g., "Fire", "Water")
limit	number	No	Max results (default 20, max 50)

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_cards",
    "arguments": {
      "query": "Pikachu",
      "setName": "Scarlet & Violet",
      "limit": 10
    }
  }
}

get_card

Get detailed information about a specific card.

Parameters:

Name	Type	Required	Description
cardId	string	No*	Card UUID
name	string	No*	Card name (exact match)
setName	string	No	Set name (helps disambiguate when using name)

*Either cardId or name is required.

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_card",
    "arguments": {
      "name": "Charizard ex",
      "setName": "Obsidian Flames"
    }
  }
}

list_sets

List all Pokemon card sets.

Parameters:

Name	Type	Required	Description
eraName	string	No	Filter by era (e.g., "Scarlet & Violet")

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_sets",
    "arguments": {
      "eraName": "Sword & Shield"
    }
  }
}

list_eras

List all Pokemon card eras.

Parameters: None

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_eras",
    "arguments": {}
  }
}

---

Price Tools

get_card_price

Get current market price for a card.

Parameters:

Name	Type	Required	Description
cardId	string	No*	Card UUID
name	string	No*	Card name
setName	string	No	Set name for disambiguation

*Either cardId or name is required.

Response includes:

• TCGPlayer market, low, mid, high prices
• eBay market price
• Combined market price
• Last updated date

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_card_price",
    "arguments": {
      "name": "Umbreon VMAX",
      "setName": "Evolving Skies"
    }
  }
}

get_price_history

Get historical price data for a card.

Parameters:

Name	Type	Required	Description
cardId	string	Yes	Card UUID
days	number	No	Days of history (default 30, max 365)

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_price_history",
    "arguments": {
      "cardId": "abc123-def456-...",
      "days": 90
    }
  }
}

get_graded_prices

Get prices for graded (PSA/CGC/BGS) versions of a card.

Parameters:

Name	Type	Required	Description
cardId	string	Yes	Card UUID
company	string	No	Grading company (PSA, CGC, BGS)
grade	number	No	Specific grade (e.g., 10, 9.5, 9)

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_graded_prices",
    "arguments": {
      "cardId": "abc123-def456-...",
      "company": "PSA",
      "grade": 10
    }
  }
}

---

Market Analytics

get_market_movers

Get cards with the biggest price changes in the last 24 hours.

Parameters:

Name	Type	Required	Description
limit	number	No	Max results (default 20, max 50)
direction	string	No	"up", "down", or "both" (default)

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_market_movers",
    "arguments": {
      "limit": 10,
      "direction": "up"
    }
  }
}

get_market_trends

Get market trends: top gainers, losers, or most valuable cards.

Parameters:

Name	Type	Required	Description
period	string	Yes	"7d", "30d", or "90d"
type	string	Yes	"gainers", "losers", or "valuable"
limit	number	No	Max results (default 10, max 50)

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_market_trends",
    "arguments": {
      "period": "30d",
      "type": "gainers",
      "limit": 20
    }
  }
}

---

Collection Valuation

value_collection

Calculate the total market value of a list of cards.

Parameters:

Name	Type	Required	Description
cards	array	Yes	List of cards to value (max 100)

Each card object:

Name	Type	Required	Description
name	string	Yes	Card name
setName	string	No	Set name for disambiguation
quantity	number	No	Quantity owned (default 1)

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "value_collection",
    "arguments": {
      "cards": [
        { "name": "Charizard ex", "setName": "Obsidian Flames", "quantity": 2 },
        { "name": "Pikachu VMAX", "setName": "Vivid Voltage", "quantity": 1 },
        { "name": "Umbreon VMAX", "setName": "Evolving Skies", "quantity": 1 }
      ]
    }
  }
}

Response includes:

• Total collection value
• Individual card prices
• Cards not found in database

---

Using with AI Assistants

Claude Desktop

Add TCGVaultHQ to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "tcgvaulthq": {
      "url": "https://tcgvaulthq.com/api/mcp",
      "headers": {
        "X-API-Key": "tcgv_live_your_key_here"
      }
    }
  }
}

Claude Code

Configure the MCP server in your Claude Code settings to access Pokemon card data directly in your coding sessions.

---

Code Examples

Python

import requests

API_KEY = "tcgv_live_your_key_here"
ENDPOINT = "https://tcgvaulthq.com/api/mcp"

def call_mcp_tool(tool_name, arguments):
    response = requests.post(
        ENDPOINT,
        headers={
            "Content-Type": "application/json",
            "X-API-Key": API_KEY
        },
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": tool_name,
                "arguments": arguments
            }
        }
    )
    return response.json()

# Search for cards
result = call_mcp_tool("search_cards", {"query": "Charizard", "limit": 5})
print(result)

# Get card price
result = call_mcp_tool("get_card_price", {"name": "Charizard ex", "setName": "Obsidian Flames"})
print(result)

JavaScript/Node.js

const API_KEY = "tcgv_live_your_key_here";
const ENDPOINT = "https://tcgvaulthq.com/api/mcp";

async function callMcpTool(toolName, args) {
  const response = await fetch(ENDPOINT, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "tools/call",
      params: {
        name: toolName,
        arguments: args
      }
    })
  });
  return response.json();
}

// Search for cards
const cards = await callMcpTool("search_cards", { query: "Pikachu", limit: 10 });
console.log(cards);

// Get market movers
const movers = await callMcpTool("get_market_movers", { direction: "up", limit: 5 });
console.log(movers);

---

Managing API Keys

Viewing Your Keys

Go to /dashboard/api-keys to see all your API keys. You'll see:

• Key name
• Key prefix (first 8 characters)
• Total requests made
• Last used date
• Creation date

Revoking a Key

If a key is compromised or no longer needed:

1. Go to /dashboard/api-keys
2. Click the trash icon next to the key
3. Confirm deletion

The key is immediately revoked - any applications using it will receive 401 errors.

Best Practices

1. Use descriptive names - Name keys after the application using them
2. Rotate keys periodically - Create new keys and deprecate old ones
3. Don't share keys - Each application should have its own key
4. Monitor usage - Check the request count to detect unusual activity
5. Store securely - Never commit API keys to version control

---

Support

Having issues? Check these common problems:

"Invalid API key" error

• Verify the key is copied correctly (no extra spaces)
• Check the key hasn't been revoked
• Ensure you're using the full key, not just the prefix

"Rate limit exceeded" error

• Wait for the rate limit window to reset (1 minute)
• Consider batching requests or adding delays
• Contact us if you need higher limits

Card not found

• Try searching with fewer filters
• Check spelling of card/set names
• Use search_cards first to find the exact card ID

For additional help, visit our feedback page or join our Discord community.