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
- Add to Cursor or via cursor.com
- Install in VS Code or VS Code Insiders
- Add to Claude Opens Settings → Connectors in Claude (web, Desktop and mobile share it). Choose Add custom connector and paste the URL above.
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
| Tool | Group | What it does |
|---|---|---|
whoami | read | The project and scopes this connection has. |
search_catalog / get_catalog_source | read | Verified sources from the public catalog, with fields, sample, terms posture and ready-made create_source arguments. No account needed. |
get_catalog_sample | read | Up 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_changes | read | What 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_source | read | Inspect 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_sources | read | Search your sources by name or URL. |
describe_source | read | Recipe, schedule, versions, latest usage rights and acquisition path. |
get_records | read | Current records, each with its evidence id and field locators, plus usage rights and the signed manifest hash. |
get_changes | read | Field-level changes between runs (before and after). |
get_changes_digest | read | What changed across all sources since a date: counts per source, the fields that moved and before/after examples. |
search_records | read | Search the current records of every source, or one field of them, and get the run each match came from. |
list_runs / get_run | read | Runs, their status, failure class and compliance state at capture. |
get_evidence | read | Captures by id or run; optionally the capture text, checked against its SHA-256. |
get_run_manifest | read | The signed manifest and its RFC 3161 timestamp anchor. |
export_run | read | A run's records as CSV, JSON or NDJSON with evidence references. |
verify_evidence | read | Runs the open verifier on a run: capture hashes, values, manifest signature, Merkle proof and timestamp, check by check. |
export_evidence_bundle | read | The WACZ evidence bundle, for offline verification. |
watch_url | build | One call for a new URL: preview it, create the source, run it and return the first records. Needs the user's rights confirmation. |
create_source | build | Start monitoring a source with a recipe you supply (with dry_run to validate first). |
update_source | build | Change schedule, record key, URL or recipe (dry_run shows the diff). |
run_source | build | Run a source now, optionally waiting up to 60 s. |
pause_source | build | Stop a source's scheduled runs (records and evidence are kept) and report the schedule to restore. |
delete_source / restore_source | build | Delete a source (asks for confirm: true; restorable for 14 days) and bring one back. |
accept_run | build | Accept a degraded run as correct. |
list_destinations / configure_delivery | deliver | Signed webhook destinations: create, pause, test. |
list_deliveries / redeliver | deliver | Delivery 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
rightsonly 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_runinstead 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.