MCP server. Agent-shaped, source-attributed.

Connect any MCP-compatible agent — Claude, Codex, Gemini, Cursor, and others — to the dataset over Model Context Protocol. Every tool response carries a source URL and source class on every value, so agents can cite the exact source record and every answer stays traceable.

MCP access is included with the Snapshot + API tier. The customer portal token covers both REST API and MCP server — same scope, same rate limits.

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.

Endpoint

http

https://api.trialbase-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.

Free to try — no token required: point any MCP client at the URL above with no Authorization header and you get the sample-scoped tools over the evaluation dataset. Every value still cites its source_url. With a token, you get the full catalogue.

Any MCP-compatible client

The server and bearer-token contract are harness agnostic. Client config wrappers are not: Claude uses JSON with an HTTP server type, Gemini uses JSON with an httpUrl, and Codex uses TOML with a token environment-variable reference.

Claude Desktop and Claude Code

~/Library/Application Support/Claude/claude_desktop_config.jsonjson

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

Gemini CLI

~/.gemini/settings.jsonjson

{
  "mcpServers": {
    "trialbase db-db": {
      "httpUrl": "https://api.trialbase-db.org/mcp",
      "headers": {
        "Authorization": "Bearer trialbase_live_····"
      }
    }
  }
}

OpenAI Codex

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

~/.codex/config.tomltoml

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

Cursor

.cursor/mcp.jsonjson

{
  "mcpServers": {
    "trialbase db-db": {
      "url": "https://api.trialbase-db.org/mcp",
      "headers": { "Authorization": "Bearer trialbase_live_····" }
    }
  }
}

Tools exposed

The following tools are registered with the MCP server. All tools are annotated read-only, idempotent, and closed-world — a miss returns an isError result so the agent can self-correct.

`trials_search`

Search trials by condition, intervention, sponsor, phase, status, country, or free text.

`trials_get`

Fetch one canonical trial by id, with every registry's provenance + cross-registry IDs.

`trials_lookup_by_ids`

Bulk registry-id (NCT / EudraCT / ISRCTN) -> canonical trial resolution.

`trials_coverage`

Per-registry / per-phase / per-status counts, date ranges, field-fill stats.

The full tool descriptions and parameter schemas are returned by the server's tools/list call — your MCP client fetches them automatically on connect.

Review the field definitions, coverage, and source notes before relying on agent output in production.

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 should cite the source_url verbatim — fabricated citations defeat the audit trail the MCP server exists to provide.

json

{
  "id": 1,
  "field_a": "example value",
  "_provenance": {
    "field_a": {
      "source": "clinicaltrials-gov",
      "source_url": "https://clinicaltrials.gov",
      "source_class": "government",
      "effective": true,
      "superseded_at": null
    }
  }
}

Data freshness

The MCP server serves the live rolling database. Corrections and new coverage are published as they arrive, with no fixed schedule. Snapshot-tier customers get versioned files; the API and MCP tier reflects the current state of the DB.