MCP

Connect#Link copied!

Endpoint: https://silphcoanalytics.xyz/api/v3/mcp/. Send Authorization: Bearer with a dashboard API key (sk_live_...) or an MCP OAuth access token. Core market tools also run without a key at the playground tier. Caller-owned tools and get_usage require a verified user identity; a browser key plus x-silph-user-tokenis supported. A get_usage call without that identity returns HTTP 401 with error: "user_required".

Muse / MCP OAuth: /connectors/muse.md. Discovery: /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/api/v3/mcp. Login is Google. Signed-in free is 2,000 API units/month and 10 chat messages/month. Pro is $12.99/mo.

Clients need the Streamable HTTP transport, custom request headers, and redirect-following — the bare path 307s to the trailing-slash URL. The server is stateless: each POST is independent (multi-worker safe); Bearer auth on every call. SDKs may still send mcp-session-id, but stale IDs are ignored.

Keyless price is REST only: GET /api/v3/price?tcg_card_id=swsh7-215&grade_key=PSA:10. Load the skill first: /skill-api.md. Full getting-started copy: /docs/reference/mcp.md.

Tools#Link copied!

Public product jobs — market data plus seller discovery, caller-owned lists, and caller-scoped usage when signed in (JWT or x-silph-user-token):

• search — card lookup: q for name/id search, or an ids list for batch resolve. Ambiguous names return candidates (never silent top-1). A query that names a set or era also returns set_matches / era_matches — pass the id as set_id or era on set-scoped tools.
• oracle — SilphCo Price per locked grain (rows with grade on every row): read price.value_usd from the price.v2 object. method and outliers select the estimator. There is no fallback across grade, finish, language, or edition: a row with status: none has a null value_usd.
• price_history / get_sales / get_listings — price history, recent sales, and live asks; all take ids lists, and sales/listings also scope by set_id.
• get_population — graded slab counts (PSA/BGS/CGC) by grade for individual cards, via ids or queries, with an optional grader filter.
• price_history — per-card or set-finish price history for charts.
• list_user_lists / get_list_contents / analyze_list_holdings — read caller-owned lists; get_list_contents accepts list_id or list_name to select a named list; paginate contents with cursor / next_cursor.
• get_list_analytics — one call of analytics for a list of 50-100+ cards: per entry, at its exact grade and finish, the price, last clean sale, 90-day median, trend, lowest live ask, population and distance to your target, plus rollups by series, grade, population band, price band and card type. Costs 1 unit per distinct card analyzed. set_watchlist_targets sets or clears per-entry target prices on a watchlist.
• add_to_watchlist / remove_from_watchlist accept optional list_id or list_name selectors for named watchlists; omitting both keeps the default Watchlist. / add_cards_to_list / remove_cards_from_list — idempotent writes scoped to the authenticated caller (no user_id param).
• create_list / rename_list / delete_list — list lifecycle. delete_list is two-step: the first call reports the item count as needs_confirm and changes nothing, then call again with confirm=true. The default Watchlist is protected; named watchlists can be renamed or deleted.
• update_holding — correct a saved lot in place: quantity (absolute, not a delta), cost_basis_usd, grade_key, finish, acquired_at, notes. add_cards_to_list only merges quantity upward and cannot set a cost basis.
• get_usage — the identified caller's own consumption: units used today against the daily limit, daily history, which endpoint families cost them, and a per-MCP-tool split (by_mcp_tool). Units are the billed quantity, not request counts.

execute_sql is not available on public MCP. Tool failures return result.isError: true with a JSON-RPC 200 — check the envelope, not just the status code.

Public MCP version 1.49.1 — market tools on every dashboard key; list tools and get_usage require a signed-in user. Agents can read the full changelog over MCP at silphco://changelog, and the published filter vocabularies at silphco://vocab; the version is also served as mcp_version on the status payload and serverInfo.version on initialize.

Agent patterns#Link copied!

Identity, then filters. search(q="Nidoking") resolves the card; pass finish="reverse_holo" on oracle or get_listings. A set title or era phrase is not a card name — pass set_id or era on set-scoped tools.

δ-era commons (ex11-ex15). get_sales(era=delta_species, rarity=Common) or get_listings(era=delta_species).

Population vs grade spread. get_population answers how many slabs exist by grade. One card's graded spread is a different question — use oracle with one row per grade.

Batch first#Link copied!

oracle, get_sales, and get_listings take ids lists; search takes q or an ids list — one call, same cost as the ids inside it.

Client config#Link copied!

{
  "mcpServers": {
    "silphco": {
      "server_url": "https://silphcoanalytics.xyz/api/v3/mcp/",
      "headers": {
        "Authorization": "Bearer ${SILPH_API_KEY}"
      }
    }
  }
}

Two entries that point at the same URL expose the same tools: the server name in your client config (Cursor shows entries such as user-silphco and user-silphco--evan) is only a local label — the account each entry acts as is set solely by the Authorization: Bearer key in that entry's headers (or by its OAuth login). Name each entry after the key it uses.

Fanatics Collect rows refresh in roughly 12-hour batches (observed about 07:00 and 19:00 UTC); weekly-auction current_bid_usd / bid_count arrive in the same batch — bids are not polled more often than fixed asks. Read each row's observed_at for its batch; per-source cadence is in the API contract notes.

Need REST instead? Agents and reference → For agents. Full handshake curl walkthrough: /docs/reference/mcp.md.