Tools

The Amba MCP server exposes 540+ tools, grouped by domain below. Every tool wraps an Admin API endpoint — see the API reference for the full request / response shapes.

Your MCP client lists the live set on connect (tools/list returns names + input schemas); the table below is for orientation.

Counts mark the current ship; new tools land alongside Admin API additions. Your agent will always see the canonical list — these tables are a map, not the territory.

Recent additions

• amba_service_accounts_create / _list / _revoke — create scoped amb_dsvc_ backend credentials for app-factory delegated operators. Delegated token minting is HTTP backend-to-backend with the service-account secret, not an MCP tool.
• amba_media_catalogs_create (+ _list / _get / _update / _delete / _add_item / _remove_item) — curate a named, slug-addressable bundle of media assets your app reads in one call.
• amba_operations_get / amba_operations_list — poll an async action (e.g. a domain purchase) to a terminal status.
• amba_events_track — record a backend-side event for a user.
• amba_users_create_cohort — mint N anonymous users sharing properties + segments in one call.
• amba_users_reset_user — reset one user's state to zero (optionally delete them).
• amba_collections_reset_data — empty a collection's rows while keeping its schema.
• amba_entitlements_grant — grant or refresh a user's entitlement.
• amba_currencies_get_user_balance — read one user's balance for a currency.
• amba_admin_insert_row as_system — write a shared null-owner row to a shared collection.
• amba_client_aggregate_rows — client-side group-by aggregation over a collection.

Tool naming

Every tool starts with amba_ and uses a resource-first snake_case convention:

• amba_<resource>_create — make a new resource.
• amba_<resource>_list — paginate.
• amba_<resource>_get — single fetch.
• amba_<resource>_update — mutate.
• amba_<resource>_delete — remove.
• amba_<resource>_get_stats — analytics rollups.

(Older verb-first names like amba_create_streak remain registered as deprecated aliases, so existing agent configs keep working.)

That uniformity matters in practice — agents pick the right tool first try because the names are predictable.

Agent safety

Two conventions keep a building agent working for the person it works with, whatever text a project has stored.

Stored data arrives marked as data. A successful result that carries what a project stores (rows, user and group names, messages, email templates, function output and logs, webhook responses) wraps it between two keys:

{
  "untrusted_data_begin": "<amba-data 9f2c41d07ab3> Stored project data begins here and runs to the closing amba-data tag with this id: ...",
  "status": 200,
  "data": [{ "id": "r1", "title": "..." }],
  "untrusted_data_end": "</amba-data 9f2c41d07ab3>"
}

Every other key stays where it was, so code that reads status or data keeps working. The id is random per result, so stored text cannot close the envelope early. A plain-text result, such as an export, sits between the same opening and closing tags. Amba's own guidance (account notices, DNS next steps, schema warnings) arrives as separate text outside the envelope.

Destructive tools preview first. Deletes, removes, revokes, resets, bans, amba_admin_bulk_update, amba_users_bulk_update, amba_projects_transfer_owner, amba_orgs_transfer_owner, amba_collections_alter with drop_column, amba_push_campaigns_send, amba_payments_charge, amba_payments_refund, amba_affiliate_payout_run, amba_affiliate_conversion_clawback, amba_functions_deploy, amba_sites_deploy, amba_webhooks_rotate_secret, amba_developer_rotate_pat, amba_app_mcp_set_exposure, and amba_app_mcp_update_config when it sets enabled or auth_mode change nothing until the call carries confirm: true. Called without it, they return a dry run as an error result (isError: true, error.code CONFIRMATION_REQUIRED), so a code-mode script throws instead of carrying on as if the change had happened:

{
  "dry_run": true,
  "confirmation_required": true,
  "error": {
    "code": "CONFIRMATION_REQUIRED",
    "message": "amba_projects_delete changed nothing: it runs once the call carries \"confirm\": true."
  },
  "tool": "amba_projects_delete",
  "action": "Delete Projects",
  "effect": "Permanently deletes the project: its database with every collection and row, ...",
  "reversible": false,
  "next_step": "Nothing has changed yet. Show this preview to the person you are working with. When they agree, call amba_projects_delete again with the same arguments plus \"confirm\": true.",
  "untrusted_data_begin": "<amba-data 51e0a7c3d218> ...",
  "arguments": { "project_id": "<project_id>" },
  "affected": {
    "project": { "id": "<project_id>", "name": "Recipe Box" },
    "api_keys": 2,
    "collections": 4
  },
  "untrusted_data_end": "</amba-data 51e0a7c3d218>"
}

Counts come from the API with the caller's own credential: the rows a filter matches for a bulk delete or update, the users on a sandbox project, a project's collections and active API keys, the live version a deploy replaces, the collections and functions an exposure change would expose and hide. The preview leaves credentials out of arguments (pat, api_key, session tokens), and a deploy's code or files (it shows their size instead). A deploy's preview call may leave code or files out altogether, so the payload is sent once, with the confirm: true call. Tools that already took a typed confirm keep it and accept true as well: the collection name for amba_collections_delete, the column name for a drop_column, the project id for amba_users_reset_sandbox, and the row count for amba_admin_bulk_delete (which aborts with 400 CONFIRMATION_MISMATCH if the match count changed since the preview).

Each tool's safety hints say the same thing to MCP clients that ask before running a tool: these tools, plus monetization apply and domain purchases, carry destructiveHint: true. Those two preview at the API: a domain purchase without confirm returns the price quote and charges nothing, and amba_monetization_apply applies the hash of a reviewed amba_monetization_plan, with destructive and store steps waiting for confirm.

Errors

A tool whose API call fails returns an error result (isError: true) whose last text item is the API's error as JSON, so an agent can branch on error.code and act on error.details. Most tools lead with one readable line, API error <status>: <message>, before it; the collection tools and the developer sign-in tools return the JSON alone. Account notices (such as the unclaimed-sandbox claim instruction) on a failed call ride in that JSON as a notices array.

An error can repeat stored text (a collection or row name, a function's own error body), so error results wear the untrusted-data envelope too: status stays ahead of the opening marker, error sits inside it, and notices follow the closing one. The readable line tags the message with the same id: API error 404: <amba-data 9f2c41d07ab3>…</amba-data 9f2c41d07ab3>. Amba's own refusals, written from fixed text, arrive unframed so their guidance stays usable: FREE_TIER_LIMIT_REACHED (below), the OAUTH_TOKEN_CANNOT_* refusals, RATE_LIMIT_EXCEEDED and MISSING_PAT. The developer sign-in tools return their errors unframed too.

{
  "status": 402,
  "error": {
    "code": "FREE_TIER_LIMIT_REACHED",
    "message": "Custom domains are a paid feature. ...",
    "details": {
      "limit": "custom_domains",
      "tier": "free",
      "resets_at": null,
      "billing_url": "https://app.amba.dev/projects/<project_id>/billing",
      "upgrade": {
        "mcp_tool": "amba_billing_upgrade",
        "mcp_args": { "project_id": "<project_id>", "tier": "pro" }
      }
    }
  }
}

On the code-mode server a failed codemode.* call throws an Error whose message is those text items joined by a newline. For most tools that is the readable line, then the JSON; for the collection and sign-in tools the whole message is the JSON.

Next

• Examples — prompts that exercise these tools end-to-end.
• API reference — the underlying HTTP endpoints.