MCP admin tools

The tools /mcp/admin serves to run an instance, the permission each needs, what each previews before it acts, and what no tool does.

/mcp/admin serves the everyday tools and these, each to a credential that holds its permission. Each call is the API call it names, made with the client's credential, so the API's permissions and refusals apply. The rules are in the contract's MCP chapter.

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
sign_ins.manage or grants.managemarfa_end_sign_inEnds an app, or with sign_ins.manage a browser sign-in or a passkey
sign_ins.managemarfa_sign_ins, marfa_rename_sign_inList sign-ins and passkeys, and rename one
backups.managemarfa_backups, marfa_take_backup, marfa_adopt_backup_folderList backups, take one now, and adopt a replaced backup disk
instance.maintainmarfa_maintain, marfa_update_serverRun a housekeeping job, cancel a bulk job, confirm the clock, and update the server
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_files, marfa_remove_file_copyList a file's copies, and remove one

marfa_connectors pages a connector's runs with runs_cursor, and marfa_trash the bin with cursor.

What no tool does

No tool claims the instance, recovers a lost password, sets the owner's password, adds a passkey, exports or restores (mcp/tools-withheld):

  • Claiming happens in the sign-in page a client opens, and recovery starts where the server runs.
  • A password must not pass through the model, and a passkey needs the browser's passkey sheet. marfa_sign_ins answers owner_page, the page for both, and marfa owner password sets the password with no echo.
  • An archive doesn't fit a tool's answer. marfa_take_backup makes a copy, and marfa export streams one.
  • No confirmation binds a restore yet.

Settings that need a recent sign-in

marfa_change_settings changes allow_private_addresses, backup_path and where files go (the object_store_ settings) only for an app whose owner signed in within 900 seconds. Otherwise it changes nothing:

  • An older sign-in gets insufficient_user_authentication, with details.max_age 900. The person signs in to that app's connection again: re-authenticate it, since a plain reconnect reuses the old sign-in. The app's next authorization, by code or device, asks them to sign in, and a refresh from the old sign-in gets invalid_grant. No other app is affected, and removing the app clears it.
  • A key gets app_sign_in_required.
  • sign_in_address gets not_offered_over_mcp for every credential, naming marfa config set sign_in_address, since moving it ends every sign-in, the agent's own included.

Previews

The tools that remove, end, replace or restart preview first and act only on the confirm token, sent by the same credential within five minutes. The instructions /mcp/admin sends tell the agent to show the person each preview.

ToolThe preview showsRefused with confirmation_stale when
marfa_revoke_keyThe keyThe key changed
marfa_manage_webhookMaking a webhook, or a new url, events or type_filterWhat the webhook would be left as changed
marfa_purgeThe ids to confirm, the items and edges it takes, hidden counts of those the credential can't read, and goes_with. Takes ids or a page; confirm with idsWhat it takes changed, or an item left the bin
marfa_end_sign_inFor kind sign_in or passkey and an id: the sign-in or passkey. For an app, its scopes, webhooks, token_chains, whether it ends_this_connection, and with revoke_keys the keys it revokesThe app, its webhooks or those keys changed, or a passkey was renamed
marfa_delete_connectorThe registration and its runs, or with part: "state" its source's state, problems and agreementsThe registration, its endpoints or deliveries, or the state changed
marfa_retire_endpointThe endpoint, which stops taking deliveries for goodThe endpoint was retired, or its registration replaced
marfa_remove_file_copyFor a hash and store_id: the copy, the other_copies, min_copies, and whether its bytes are deleted or keptThe store no longer holds that copy
marfa_adopt_backup_folderThe folder, the store it replaces, what the instance forgets, files_to_purge and last_backupThe folder or what it forgets changed
marfa_update_serverThe release it runs and the release it moves toA newer release was found
marfa_maintain, action: "confirm_clock"The gap_seconds, the held_jobs and hold_ends_at; held: false and no token when nothing waitsThe clock jumped, or nothing is held
  • marfa_end_sign_in refuses a key, with use_tool naming marfa_revoke_key. Without revoke_keys, an app's keys stay.
  • marfa_remove_file_copy refuses a removal below the minimum with copies_below_minimum.
  • marfa_adopt_backup_folder answers marked: true once the new store's marker is written, false with marker_error, or null when the folder didn't answer in time. folder_changed is true when the folder read otherwise once marked. Files the operating system adds, such as .DS_Store, don't make the token stale.
  • marfa_update_server refuses as POST /update does, with that code and its details.step.
  • A token works once. Sent again, marfa_purge answers already_purged, marfa_manage_webhook a refusal, and the connector tools, marfa_end_sign_in, marfa_remove_file_copy, marfa_adopt_backup_folder and confirm_clock already_done.

On this page