MCP server. Spec values, source URLs, agent-shaped.

Endpoint

https://mcp.apex-db.org/mcp

MCP runs over the Streamable HTTP transport. Client configuration: the URL above, bearer token in the Authorization header. On a 401 the server returns a WWW-Authenticate header pointing at its OAuth 2.0 Protected Resource Metadata (RFC 9728), so compliant clients can discover how to authenticate.

Pay-per-call settlement is currently exposed by the REST API, not as a discoverable MCP payment challenge. A tokenless MCP client remains sample-scoped; use a bearer token for full MCP access, or call the REST API for an isolated paid lookup. See API → Agent payments for x402 (USDC on Base) or MPP (USDC on Base and Tempo) and pricing.

Any MCP-compatible client

The server and bearer-token contract are harness agnostic. Claude, Gemini, Codex, and Cursor use different config wrappers around the same Streamable HTTP endpoint.

Claude Desktop and Claude Code

{
  "mcpServers": {
    "apex-db": {
      "type": "http",
      "url": "https://mcp.apex-db.org/mcp",
      "headers": {
        "Authorization": "Bearer apex_live_····"
      }
    }
  }
}

Gemini CLI

{
  "mcpServers": {
    "apex-db": {
      "httpUrl": "https://mcp.apex-db.org/mcp",
      "headers": { "Authorization": "Bearer apex_live_····" }
    }
  }
}

OpenAI Codex

Put the portal token in DBSET_API_TOKENso it stays out of the checked-in config file.

[mcp_servers.apex-db]
url = "https://mcp.apex-db.org/mcp"
bearer_token_env_var = "DBSET_API_TOKEN"
enabled = true

Cursor

{
  "mcpServers": {
    "apex-db": {
      "url": "https://mcp.apex-db.org/mcp",
      "headers": { "Authorization": "Bearer apex_live_····" }
    }
  }
}

Tools exposed

apex_search_variants

Natural-language search across brand, model, model year, and powertrain. Default 25 candidates; paid callers up to 100, ranked by match relevance. The fallback when the agent has a name ("RAV4 Hybrid XLE AWD 2024") but not a structured filter.

apex_get_variant

Full row by variant ID, with the _provenance subtree on every spec field.

apex_lookup_by_portfolio

Bulk variant resolution for a portfolio of identity-id objects — each { scheme, value } pair is a type-approval or national registration id. Returns { results: [{ scheme, value, variant_id|null }] }, with unmatched ids carrying variant_id: null.

apex_coverage_matrix

Returns the same matrix shown at /docs/coverage. Filterable by field group, era, and powertrain.

Response shape

Every tool returns its result as structuredContent (machine-readable) alongside a JSON text block, and carries a _provenance map keyed by field. Agent integrations cite the source_url verbatim; fabricated citations defeat the audit trail the MCP server exists to provide. All four tools are annotated read-only, idempotent, and closed-world, and a miss returns an isError result so the agent can self-correct.

{
  "id": 95124,
  "brand": "BMW",
  "model": "5 Series",
  "co2_combined_g_km": 182,
  "_provenance": {
    "co2_combined_g_km": {
      "source": "transport-canada",
      "source_url": "https://open.canada.ca/data/en/dataset/98f1a129-f628-4ce4-b24d-6f16bf24dd64",
      "source_class": "government",
      "pcaf_dq": 2,
      "applies_to_year_start": 2026,
      "applies_to_year_end": 2026
    }
  }
}

Data freshness

The MCP server serves the live rolling database — corrections and new coverage flow continuously, on an ad-hoc basis with no fixed schedule. Snapshot SKU customers get versioned files; the API and MCP tier reflects the current state of the DB.