Docs / MCP server

MCP server

Wire gold prices directly into Claude Desktop, Cursor, or any MCP-compatible agent. Six tools, 30-second setup, available on every plan — including Free.

§Why MCP

Model Context Protocol lets an LLM call your tools directly, with native schemas the model can reason about. When a user asks Claude "what's gold in rupees per gram today?", MCP lets Claude call get_spot_price with the right arguments instead of guessing.

We expose six tools, all thin wrappers around the REST endpoints you already know. Same auth, same rate limits, same staleness semantics — just structured for agent use.

§Install in 30 seconds

Pick your path. Global install gives you a local mcp binary and skips the per-launch npm download; the npx variant in the Claude Desktop + Cursor panes works with zero prior setup.

# One-time global install
npm install -g @goldprice/mcp

# Then reference the installed binary in your MCP client config:
#   "command": "mcp"   (not "npx")

# Verify it's on PATH:
which mcp
# Edit ~/Library/Application Support/Claude/claude_desktop_config.json
# (on Windows: %APPDATA%\Claude\claude_desktop_config.json)
{
  "mcpServers": {
    "goldprice": {
      "command": "npx",
      "args": ["-y", "@goldprice/mcp"],
      "env": {
        "GP_KEY": "ga_live_a94f…2c71"
      }
    }
  }
}

# Restart Claude. The icon should show "goldprice" with the tools available on your plan.
// .cursor/mcp.json at repo root or ~/.cursor/mcp.json
{
  "mcpServers": {
    "goldprice": {
      "command": "npx",
      "args": ["-y", "@goldprice/mcp"],
      "env": { "GP_KEY": "ga_live_..." }
    }
  }
}

// Ctrl/Cmd-Shift-P → "Restart MCP servers"
# Any MCP client: point it at the stdio server directly
npx -y @goldprice/mcp

# Environment variables:
#   GP_KEY       required — your API key
#   GP_BASE_URL  optional — defaults to https://api.goldprice.dev
#   GP_TIMEOUT   optional — ms, defaults to 10000

§Available tools

All six tools are listable and callable at every tier. Per-symbol scope follows your plan tier and is enforced by the REST API underneath — e.g. Free can invoke get_spot_price with XAG-USD-SPOT but the underlying response returns 403 plan_gated because silver is Pro-gated. The one inline MCP-level gate is get_historical: Free and Basic see the last 30 days; Pro unlocks the full history window.

get_spot_price— latest aggregated spot (or GC futures) price for one symbol. "What's gold trading at right now in INR?" Symbol scope per tier.
list_commodities— catalog of supported symbols. Call this first when you don't know the valid symbol for a currency or contract.
get_metadata — per-symbol provenance: sources, unit, staleness rules, methodology URL, commercial-use notes. Use for attribution and data-lineage documentation.
get_historical — daily close series between two dates. Free + Basic limited to last 30 days; Pro unlocks full history.
search_news — metals news headlines. MVP stub at launch; real indexing ships Week 1 post-launch with the Gold Brief newsletter RSS pipeline.
search_docs — BM25 search over the bundled FAQ corpus. Use before answering how-to / billing / auth questions so you cite canonical text instead of guessing.

§Rate limits per tier

MCP calls share the same per-key rate limit as REST. Heavy agent usage (think: scripted backtests in a loop) lives on Pro; interactive chat fits comfortably in Basic.

Tier	Rate limit	Symbol scope	Tools available
Free	30 / min	XAU spot · 13 currencies	All 6
Basic	120 / min	XAU spot + futures	All 6
Pro	500 / min	XAU + XAG spot + futures · HG futures	All 6

§Troubleshooting

Claude doesn't see the tools?

Fully quit Claude (Cmd-Q, not just close the window) and reopen. MCP servers load once, on launch. If the icon still shows "0 tools", check the config JSON parses — a trailing comma is the usual culprit.

Getting "invalid_api_key"?

Make sure GP_KEY is set in the env block, not the shell. Claude Desktop doesn't inherit your terminal's environment — it reads config JSON literally.

Still stuck? Email hello@goldprice.dev.