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

EndpointToolsFor
/mcpThe everyday toolsFinding, reading, saving and changing items
/mcp/schemaThe everyday and schema toolsShaping what the instance holds: types, views and sources
/mcp/adminThe everyday and admin toolsRunning 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:

Response
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-resource and the endpoint's path. Every endpoint lists the scopes content:read, content:write, edge.*:read, edge.*:write and offline_access. /mcp/schema adds metadata.types:write, schema.write and system.view:write, and /mcp/admin adds 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-server only.
  • 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 403 with WWW-Authenticate: Bearer error="insufficient_scope" and the scope to 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 Origin gets 403 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

ToolWhat it does
marfa_overviewTypes with counts, edge types, top tags, views and folders. With type, its fields and tables
marfa_findSearches by words, or lists by type, tags, source, state, tier or dates: 20 entries, up to 50
marfa_getReads 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_rowsReads the rows of an item's table, with a filter, a sort and totals: 50 rows, up to 1,000
marfa_createCreates an item, or saves a file from a web address or a chat
marfa_updateSets or clears fields, or changes tags, edges, tier or state, such as a restore from the bin
marfa_write_rowsPuts, patches or deletes up to 200 rows, written whole or not at all
marfa_deleteMoves up to 20 items to the bin, after a preview

Schema tools

ToolWhat it doesOffered when the credential
marfa_save_typeRegisters or changes a typeMay register types, or holds schema.write
marfa_save_viewMakes or changes a saved viewWrites system.view
marfa_move_itemsMoves every item of one type to another as a job, after a previewWrites a type
marfa_bulk_saveCreates up to 200 items, or with mode: "upsert" updates saved onesWrites a type
marfa_search_docsSays where to search these docsAlways
marfa_sourcesLists each source's name and markAlways
marfa_name_sourceNames a source: its own, one it claims, or any with keys.manageAlways

Admin tools

PermissionToolsWhat they do
instance.read or connectors.managemarfa_healthHealth 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.readmarfa_auditReads the audit log, newest first
keys.mint or keys.managemarfa_keys, marfa_manage_key, marfa_revoke_keyList, make, change and revoke keys
webhooks.managemarfa_webhooks, marfa_manage_webhookList, make, change, pause or delete webhooks
config.managemarfa_settings, marfa_change_settingsRead and change the settings
items.purgemarfa_trash, marfa_purgeList and purge the bin
grants.managemarfa_apps, marfa_narrow_appList apps, and narrow one
backups.managemarfa_backups, marfa_take_backupList backups, and take one now
instance.maintainmarfa_maintainRuns a housekeeping job, or cancels a bulk job
connectors.managemarfa_connectors, marfa_make_endpoint, marfa_delete_connector, marfa_retire_endpointRead, delete or reset connectors, and make or retire an inbound endpoint
blobs.managemarfa_filesLists a file's copies
sign_ins.managemarfa_sign_ins, marfa_rename_sign_inList 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_webhook previews only making a webhook or changing its url, events or type_filter.
  • marfa_purge takes ids, up to 200 items in the bin, or a page of it. The preview answers the ids to confirm, the items and edges it takes, hidden counts of those the key can't read, and goes_with. Confirm with ids, never page.
  • marfa_delete_connector deletes a registration and its runs, or with part: "state" clears its source's state, problems and agreements. marfa_retire_endpoint stops an endpoint taking deliveries for good.
  • A token is refused with confirmation_stale when another credential sends it, after five minutes, or once what the preview showed changed, even unreadable items.
  • A token works once. Sent again, marfa_delete answers already_trashed, marfa_purge already_purged, the connector tools already_done, and marfa_manage_webhook a 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_rows and marfa_trash answer a next_cursor when more follows; send it back as cursor. marfa_connectors pages a connector's runs with runs_cursor.
  • marfa_get keeps each answer within 40,000 characters. cut names each cut field by id, field and next_offset; call again with those, as offset, for the rest. not_returned names 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:

reasonWhen
not_public, redirectNot a public address, or a redirect
bad_url, unreachableNot http or https, or no answer
statusAn error answer, as from a chat's expired attachment link
too_large, timeoutPast mcp_fetch_max_bytes (50 MiB) or mcp_fetch_timeout_seconds (60)
busy, rate_limitedFour fetches running, or 30 in rate_limit_window_seconds; retry after retry_after_seconds
disabledmcp_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 initialize handshake, and 2025-11-25 and earlier through initialize, with the same tools.
  • No sessions or streams: nothing is kept between requests, and subscriptions/listen answers -32601. Follow changes with events.
  • Audit: a tool's write is recorded with the credential, the caller's address and "via": "mcp".

On this page