Docs · Developers

MCP server

SourceFinch runs a remote Model Context Protocol server, so AI assistants such as Claude, ChatGPT, Cursor or VS Code can find and configure your sources, run them, and read records together with the evidence each value came from and its usage rights. It uses the same API, limits and permissions as the REST API and the SDK.

Connect

Add a remote (Streamable HTTP) MCP server with this URL:

https://sourcefinch.com/mcp

Try it without an account

https://sourcefinch.com/mcp/public answers without sign-in. Your assistant can search the Verified catalog, read a source, see sample records and what changed in the last 7 days, and preview a public URL in a limited way (the tools marked “No account needed” below). Samples and change values are shown only for sources whose recorded usage rights allow redistribution. Every other tool is listed with “Requires sign-in”; calling one asks your client to connect a free account, and from then on the same address is the full server.

Calls without an account are limited to 30 a minute and 300 an hour per client, 1,000 an hour per network address, and the preview to 5 an hour and 20 a day. Some clients (Cursor, Claude Desktop in managed mode) only start sign-in when the first request is refused, so for everyday use connect to https://sourcefinch.com/mcp.

One-click install

Any client that reads mcp.json:

{
  "mcpServers": {
    "sourcefinch": {
      "type": "http",
      "url": "https://sourcefinch.com/mcp"
    }
  }
}

SourceFinch is listed in the official MCP Registry as com.sourcefinch/sourcefinch. Connecting needs a free account: sign up.

Your client opens a SourceFinch sign-in and consent page. Choose the project it may use and whether it may also make changes (editors and owners only). The client receives a token for that project only, refreshed every hour. Disconnect it any time in Console → Security → Connected apps.

Claude Code, for example:

claude mcp add --transport http sourcefinch https://sourcefinch.com/mcp

Headless agents can skip OAuth and send a project API key instead: Authorization: Bearer sec_….

Clients that only run local servers can use the stdio bridge @sourcefinch/mcp (same tools, an API key instead of OAuth). It is not on npm yet; until it is, ask us for a build.

{ "mcpServers": { "sourcefinch": {
    "command": "npx", "args": ["-y", "@sourcefinch/mcp"],
    "env": { "SOURCEFINCH_API_KEY": "sec_…" } } } }

Tools

ToolGroupWhat it does
whoamireadThe project and scopes this connection has.
search_catalog / get_catalog_sourcereadVerified sources from the public catalog, with fields, sample, terms posture and ready-made create_source arguments. No account needed.
get_catalog_samplereadUp to five records from the latest verified run of a Verified source, with the capture's SHA-256. No account needed; values only where the source's usage rights allow redistribution.
get_catalog_changesreadWhat changed in a Verified source in the last 7 days: counts per day, the fields that moved and examples before and after. No account needed; values only where usage rights allow redistribution.
preview_sourcereadInspect a URL before creating anything: the records found, a proposed recipe and key, sample rows, and better feeds or APIs. Without an account: a limited preview (5 records, 8 fields, no recipe).
find_sourcesreadSearch your sources by name or URL.
describe_sourcereadRecipe, schedule, versions, latest usage rights and acquisition path.
get_recordsreadCurrent records, each with its evidence id and field locators, plus usage rights and the signed manifest hash.
get_changesreadField-level changes between runs (before and after).
get_changes_digestreadWhat changed across all sources since a date: counts per source, the fields that moved and before/after examples.
search_recordsreadSearch the current records of every source, or one field of them, and get the run each match came from.
list_runs / get_runreadRuns, their status, failure class and compliance state at capture.
get_evidencereadCaptures by id or run; optionally the capture text, checked against its SHA-256.
get_run_manifestreadThe signed manifest and its RFC 3161 timestamp anchor.
export_runreadA run's records as CSV, JSON or NDJSON with evidence references.
verify_evidencereadRuns the open verifier on a run: capture hashes, values, manifest signature, Merkle proof and timestamp, check by check.
export_evidence_bundlereadThe WACZ evidence bundle, for offline verification.
watch_urlbuildOne call for a new URL: preview it, create the source, run it and return the first records. Needs the user's rights confirmation.
create_sourcebuildStart monitoring a source with a recipe you supply (with dry_run to validate first).
update_sourcebuildChange schedule, record key, URL or recipe (dry_run shows the diff).
run_sourcebuildRun a source now, optionally waiting up to 60 s.
pause_sourcebuildStop a source's scheduled runs (records and evidence are kept) and report the schedule to restore.
delete_source / restore_sourcebuildDelete a source (asks for confirm: true; restorable for 14 days) and bring one back.
accept_runbuildAccept a degraded run as correct.
list_destinations / configure_deliverydeliverSigned webhook destinations: create, pause, test.
list_deliveries / redeliverdeliverDelivery receipts and redelivery.

Read tools are marked read-only; write tools are hidden from read-only connections. To load only some tools, connect to https://sourcefinch.com/mcp?groups=read (groups: read, build, deliver). Sources and runs are also resources: sourcefinch://sources/{id}, sourcefinch://sources/{id}/records, sourcefinch://runs/{id}; sourcefinch://changes/latest is the last seven days of changes.

Clients that show prompts offer four: what_changed, monitor_topic, watch_url and export_with_evidence.

Monitor a URL in one call

Give the assistant a URL and ask it to watch it. watch_url inspects the page, creates a source from the records it finds, runs it once and returns the first records, with the feeds or APIs it found that carry the same data.

  • The assistant must ask you first whether you have the right to collect the source. It sets rights only from your answer.
  • If the page has no repeated records, nothing is created.
  • If the first run fails or is still going, the source stays and keeps its schedule. The answer says so, and the assistant checks the run with get_run instead of watching the URL again.
  • It uses one inspection (60 an hour), one place on your plan and one run. Failed runs are free.

For full control, use the three separate tools: preview_source to see the candidates and the proposed recipe, create_source (with dry_run first) to create exactly what you reviewed, and run_source to start it. For a Verified catalog source, use monitor_catalog_source.

Ground rules

  • Runs started by an assistant count against your plan like any other run; failed runs are free.
  • SourceFinch respects robots.txt and never bypasses logins or bot challenges, whoever asks. Create sources only for data you have the right to collect.
  • Usage rights describe documented provenance and terms at capture time. They are not legal advice.

For client developers

Authorization follows the MCP specification: protected resource metadata at /.well-known/oauth-protected-resource/mcp, authorization server metadata at /.well-known/oauth-authorization-server, dynamic client registration, authorization code with PKCE (S256), the resource parameter, and rotating refresh tokens. Clients are public (no secret). Supported protocol versions: 2025-11-25, 2025-06-18 and 2025-03-26.