Marfa MCP server
The endpoints and tools an instance serves to AI agents over MCP, how a client signs in, and the rules a tool call meets.
Every instance serves MCP at /mcp, over the Streamable HTTP transport. Each tool call is an API call made with the credential the client sent, so the API's permissions, refusals and limits apply. To connect, see Connect your agent.
The rules are in the contract's MCP chapter.
Endpoints
| Endpoint | Tools | For |
|---|---|---|
/mcp | The everyday tools | Finding, reading, saving and changing items |
/mcp/schema | The everyday and schema tools | Shaping what the instance holds: types, views and sources |
/mcp/admin | The everyday and admin tools | Running the instance |
Connect an agent to the smallest endpoint it needs. Each takes only POST.
Sign-in and discovery
A request carries a key or an app's access token as a Bearer credential, or gets a challenge:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://marfa.example.com/.well-known/oauth-protected-resource/mcp"- Protected resource metadata is at
/.well-known/oauth-protected-resourceand the endpoint's path. Every endpoint lists the scopescontent:read,content:write,edge.*:read,edge.*:writeandoffline_access./mcp/schemaaddsmetadata.types:write,schema.writeandsystem.view:write, and/mcp/adminadds each permission in the admin tools table, so Full access shows every tool. - The authorization server is the instance, whose origin is the issuer, with no path or trailing slash, such as
https://marfa.example.com. Its metadata is at/.well-known/oauth-authorization-serveronly. - The client signs in as any app does (Authenticate), with the instance's origin or one endpoint's address as
resource. Its token works at the API and every endpoint, within what the owner granted. - A client can ask for more access. When an app's token lacks a scope a tool call needs, the endpoint answers
403withWWW-Authenticate: Bearer error="insufficient_scope"and thescopeto ask for, before anything changes. A key gets a tool error instead. - A browser page calls an endpoint only from the instance's origin or an approved page's. Any other
Origingets403 forbidden.
Tools
An endpoint lists only the tools a credential can use. A credential that may write a type gets all eight everyday tools, and a reader the four that read.
Everyday tools
| Tool | What it does |
|---|---|
marfa_overview | Types with counts, edge types, top tags, views and folders. With type, its fields and tables |
marfa_find | Searches by words, or lists by type, tags, source, state, tier or dates: 20 entries, up to 50 |
marfa_get | Reads up to 20 items in full, with versions and tables; edges adds edges, and file_link a file's download link for ttl_seconds |
marfa_read_rows | Reads the rows of an item's table, with a filter, a sort and totals: 50 rows, up to 1,000 |
marfa_create | Creates an item, or saves a file from a web address or a chat |
marfa_update | Sets or clears fields, or changes tags, edges, tier or state, such as a restore from the bin |
marfa_write_rows | Puts, patches or deletes up to 200 rows, written whole or not at all |
marfa_delete | Moves up to 20 items to the bin, after a preview |
Schema tools
| Tool | What it does | Offered when the credential |
|---|---|---|
marfa_save_type | Registers or changes a type | May register types, or holds schema.write |
marfa_save_view | Makes or changes a saved view | Writes system.view |
marfa_move_items | Moves every item of one type to another as a job, after a preview | Writes a type |
marfa_bulk_save | Creates up to 200 items, or with mode: "upsert" updates saved ones | Writes a type |
marfa_search_docs | Says where to search these docs | Always |
marfa_sources | Lists each source's name and mark | Always |
marfa_name_source | Names a source: its own, one it claims, or any with keys.manage | Always |
Admin tools
| Permission | Tools | What they do |
|---|---|---|
instance.read or connectors.manage | marfa_health | Health and each connector's last run. instance.read adds errors, attention, housekeeping, metrics, file stores, updates and a bulk job; unread names a part it couldn't read |
audit.read | marfa_audit | Reads the audit log, newest first |
keys.mint or keys.manage | marfa_keys, marfa_manage_key, marfa_revoke_key | List, make, change and revoke keys |
webhooks.manage | marfa_webhooks, marfa_manage_webhook | List, make, change, pause or delete webhooks |
config.manage | marfa_settings, marfa_change_settings | Read and change the settings |
items.purge | marfa_trash, marfa_purge | List and purge the bin |
grants.manage | marfa_apps, marfa_narrow_app | List apps, and narrow one |
backups.manage | marfa_backups, marfa_take_backup | List backups, and take one now |
instance.maintain | marfa_maintain | Runs a housekeeping job, or cancels a bulk job |
connectors.manage | marfa_connectors, marfa_make_endpoint, marfa_delete_connector, marfa_retire_endpoint | Read, delete or reset connectors, and make or retire an inbound endpoint |
blobs.manage | marfa_files | Lists a file's copies |
sign_ins.manage | marfa_sign_ins, marfa_rename_sign_in | List sign-ins and passkeys, and rename one |
marfa_change_settings answers app_sign_in_required, changing nothing, for a setting that needs a recent sign-in.
No tool does what a preview can't yet bind or needs the owner in person, such as revoking an app, removing a file's copy, restoring, claiming or anything with passkeys or the password. mcp/tools-withheld lists them all, and the owner does them with the CLI.
readOnlyHint marks the tools that only read, and destructiveHint every other except marfa_create, marfa_name_source, marfa_change_settings, marfa_take_backup, marfa_make_endpoint and marfa_rename_sign_in. openWorldHint marks those that can reach outside the instance: marfa_create, marfa_manage_webhook, marfa_take_backup, marfa_maintain and marfa_change_settings.
Previews and confirmation
marfa_delete, marfa_move_items, marfa_revoke_key, marfa_manage_webhook, marfa_purge, marfa_delete_connector and marfa_retire_endpoint act in two calls. The first changes nothing and answers a preview with a confirm token; once the person agrees, the agent sends the same arguments with the token.
marfa_delete's preview names every item it moves.marfa_manage_webhookpreviews only making a webhook or changing itsurl,eventsortype_filter.marfa_purgetakesids, up to 200 items in the bin, or apageof it. The preview answers theidsto confirm, theitemsandedgesit takes,hiddencounts of those the key can't read, andgoes_with. Confirm withids, neverpage.marfa_delete_connectordeletes a registration and its runs, or withpart: "state"clears its source's state, problems and agreements.marfa_retire_endpointstops an endpoint taking deliveries for good.- A token is refused with
confirmation_stalewhen another credential sends it, after five minutes, or once what the preview showed changed, even unreadable items. - A token works once. Sent again,
marfa_deleteanswersalready_trashed,marfa_purgealready_purged, the connector toolsalready_done, andmarfa_manage_webhooka refusal.
Changing an item
marfa_update takes the version the agent read. Unlike Update an item, it never merges a stale change: if the item changed since, nothing is written, and version_conflict holds the item in current and, in conflicting_fields, each field of the call changed since. If it changes partway through a call, the error names the refused step in failed_step and those written in applied.
Long answers
marfa_find,marfa_read_rowsandmarfa_trashanswer anext_cursorwhen more follows; send it back ascursor.marfa_connectorspages a connector's runs withruns_cursor.marfa_getkeeps each answer within 40,000 characters.cutnames each cut field byid,fieldandnext_offset; call again with those, asoffset, for the rest.not_returnednames the items that didn't fit.
Saving a file
marfa_create saves a file from a web address in url, or one attached in a chat in file, as a file item. It fetches only from public addresses, with no redirect, and answers a refusal file_not_fetched with a reason:
reason | When |
|---|---|
not_public, redirect | Not a public address, or a redirect |
bad_url, unreachable | Not http or https, or no answer |
status | An error answer, as from a chat's expired attachment link |
too_large, timeout | Past mcp_fetch_max_bytes (50 MiB) or mcp_fetch_timeout_seconds (60) |
busy, rate_limited | Four fetches running, or 30 in rate_limit_window_seconds; retry after retry_after_seconds |
disabled | mcp_fetch_enabled is false |
The mcp_fetch_* settings apply from the next fetch.
Tool errors
A refused call is a tool result with isError set, holding one JSON object:
{ "error": { "code": "version_conflict", "message": "…", "hint": "Read the item again with marfa_get…" } }The code is an API error code, or the tools' own confirmation_stale or file_not_fetched. An argument the tool doesn't take is refused by name.
Protocol
- Revisions: MCP 2026-07-28 with no
initializehandshake, and 2025-11-25 and earlier throughinitialize, with the same tools. - No sessions or streams: nothing is kept between requests, and
subscriptions/listenanswers-32601. Follow changes with events. - Audit: a tool's write is recorded with the credential, the caller's address and
"via": "mcp".