# Marfa MCP server (/reference/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](/connect-your-agent).

The rules are in the contract's [MCP chapter](https://github.com/withmarfa/marfa/blob/main/conformance/spec/mcp.md).

## Endpoints [#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 [#sign-in-and-discovery]

A request carries a key or an app's access token as a Bearer credential, or gets a challenge:

```http title="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](#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](/build/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](/build/connect-a-web-page).** Any other `Origin` gets `403 forbidden`.

## Tools [#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 [#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](/build/tables), 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 [#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 [#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](/use/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](/run/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](/run/sign-in-as-the-owner#confirm-its-you).

**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`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/mcp.md#mcptools-withheld) lists them all, and the owner does them with the [CLI](/reference/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 [#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 [#changing-an-item]

`marfa_update` takes the `version` the agent read. **Unlike [Update an item](/reference/api/items/updateItem), 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 [#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 [#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](/build/files). 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](/run/settings) apply from the next fetch.

## Tool errors [#tool-errors]

A refused call is a tool result with `isError` set, holding one JSON object:

```json
{ "error": { "code": "version_conflict", "message": "…", "hint": "Read the item again with marfa_get…" } }
```

The `code` is an API [error code](/reference/errors#codes), or the tools' own `confirmation_stale` or `file_not_fetched`. An argument the tool doesn't take is refused by name.

## Protocol [#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](/build/events).
* **Audit:** a tool's write is recorded with the credential, the caller's address and `"via": "mcp"`.
