Tools

The Amba MCP server exposes 500+ 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.

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.

{
  "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.