Amba
MCP Server

Install

Connect Claude Code, Cursor, Windsurf, or Claude.ai web to the Amba MCP server.

The fastest way to connect any MCP-aware AI coding agent to Amba is to let the CLI do it:

npx -y @layers/amba init

When invoked from a coding agent's bash tool (non-TTY), amba init runs headlessly — no browser, no prompts. It signs you up over HTTPS, provisions a sandbox-tier project, writes .env.local + AMBA.md into your current directory, installs the /amba skill into every detected agent skill directory, and merges an amba entry into every MCP client config it finds on disk.

✓ Amba ready
  project: proj_abc12… (sandbox-1747234567-abc123@layers.com)
  keys → /Users/me/my-app/.env.local
  mcp → /Users/me/.claude.json, /Users/me/.cursor/mcp.json (active next agent launch)
  skill → /Users/me/my-app/.claude/skills/amba/SKILL.md

  next: npm install @layers/amba-web
        Amba.configure({ projectId: process.env.AMBA_PROJECT_ID, clientKey: process.env.AMBA_CLIENT_KEY })
  later: amba claim <your-email> to upgrade past sandbox

The install is complete the moment the CLI exits. The MCP entry has been persisted; it activates automatically on the next launch of your MCP client (Claude Code, Cursor, Windsurf). For tool calls in the current session — useful when the agent that just ran the CLI wants to keep working without you closing it — pass pat as an inline argument on every amba_* tool call (the PAT lives in ~/.amba/credentials.json and was emitted in the CLI output).

When you're ready to bind the sandbox account to a real email and lift the caps to the Free tier (1,000 MAU, 500 MB DB), run:

npx @layers/amba claim me@example.com

You'll get a one-click magic link in your inbox; clicking it promotes the project and lets you sign in from a browser if you ever need to.

What the CLI configures

The amba init flow probes these locations and merges into the ones that exist (or scaffolds the global ones if missing):

ClientConfig path
Claude Code (global)~/.claude.json
Claude Code (project-local)<cwd>/.mcp.json (only if it already exists)
Cursor (global)~/.cursor/mcp.json
Cursor (project-local)<cwd>/.cursor/mcp.json (only if it already exists)
Windsurf~/.codeium/windsurf/mcp_config.json

The merged entry is:

{
  "mcpServers": {
    "amba": {
      "type": "http",
      "url": "https://mcp.amba.dev/mcp",
      "headers": { "Authorization": "Bearer <your-pat>" }
    }
  }
}

Existing mcpServers.* entries are preserved — only mcpServers.amba is overwritten.

Useful flags

amba init --sandbox-email me@example.com   # override the auto-generated sandbox email
amba init --no-mcp-config                  # skip the MCP-client-config write step
amba init --json                           # machine-readable summary for agents

amba init auto-detects non-TTY invocations (the bash-tool case) and routes through the sandbox-signup path. Explicit --sandbox and --json flags also force it. There is no separate "sandbox vs full" mode on the wire — the only thing the headless path adds is generating an email + password.

In-agent signup (via MCP)

If an agent is already pointed at the Amba MCP server but no developer account exists yet, it can provision one inline by calling the public amba_developer_signup tool. The response includes ready-to-paste config snippets — one per MCP client — so the agent can write the right snippet to disk without inventing JSON shapes:

{
  "pat": "amb_dpat_…",
  "project": {
    "project_id": "…",
    "client_key": "…",
    "server_key": "…",
    "provisioning_status": "provisioning",
    "verify_url": "…",
    "verify_token": "…"
  },
  "mcp_config": {
    "claude_code": {
      "path_hint": "~/.claude.json (global) or .mcp.json in the project root",
      "snippet": {
        "mcpServers": {
          "amba": {
            "type": "http",
            "url": "https://mcp.amba.dev/mcp",
            "headers": { "Authorization": "Bearer amb_dpat_…" }
          }
        }
      }
    },
    "cursor": {
      "path_hint": "~/.cursor/mcp.json (global) or .cursor/mcp.json in project root",
      "snippet": {
        "mcpServers": {
          "amba": {
            "type": "http",
            "url": "https://mcp.amba.dev/mcp",
            "headers": { "Authorization": "Bearer amb_dpat_…" }
          }
        }
      }
    },
    "windsurf": {
      "path_hint": "~/.codeium/windsurf/mcp_config.json",
      "snippet": {
        "mcpServers": {
          "amba": {
            "serverUrl": "https://mcp.amba.dev/mcp",
            "headers": { "Authorization": "Bearer amb_dpat_…" }
          }
        }
      }
    }
  },
  "agent_instructions": "The PAT is in your hand right now — keep building in THIS session immediately. Pass `pat: \"<the pat from this response>\"` as an inline argument on every subsequent `amba_*` tool call. The inline `pat` arg overrides the inbound Bearer for that one call, so no client config change is needed mid-session. For future sessions: write the matching snippet from `mcp_config` to the customer's MCP client config file (merge with any existing `mcpServers` block — do not overwrite). Next time the MCP client starts it sends the PAT as the inbound Bearer automatically and the inline `pat` arg becomes optional. The customer does not need to do anything."
}

The agent uses the PAT inline on every subsequent amba_* tool call in the same session (no restart, no client config change needed mid-session) and writes the matching snippet to the customer's MCP config so future sessions pick the PAT up as the inbound Bearer automatically.

amba_developer_login returns the same mcp_config shape for returning customers.

Lifting the sandbox cap

Two paths, depending on whether the developer wants to bind a real email address.

Recommended (binds a real email): run npx @layers/amba claim me@example.com from the terminal. Agents without shell access can POST { "email": "<target>" } to /v1/auth/developer/claim with Authorization: Bearer <pat> directly. The backend emails a one-click magic link to that address; clicking it promotes the developer from agent_sandbox to verified_free AND updates developers.email so they can sign in from a browser later.

Headless (keeps the auto-generated sandbox email): call amba_developer_verify with the verify_token from the signup response. This lifts the MAU cap immediately but keeps the developer's email as the sandbox-generated sandbox-<epoch>-<nonce>@layers.com. Useful for fully-autonomous CI flows that never have a real inbox to claim against.

{
  "tool": "amba_developer_verify",
  "args": { "verify_token": "<value from project.verify_token>" }
}

The tool returns the developer record with the upgraded tier:

{
  "data": {
    "verified": true,
    "already_verified": false,
    "developer": {
      "id": "dev_…",
      "tier": "verified_free",
      "is_verified": true
    }
  },
  "status": 200
}

Tokens are single-use and expire after 7 days. A re-call with the same token after the developer is verified returns 200 with already_verified: true — safe to retry on a flaky network. The browser-clickable verify_url carries the same token; either path consumes it. The response does not echo the developer email — agents that need it should call amba_developer_me with the inbound PAT.

When to use the in-agent path

For most flows the CLI (amba init) is the canonical path because it also writes .env.local, AMBA.md, the /amba skill bundle, and (where applicable) updates project-local MCP configs. Use the in-agent path (amba_developer_signup + inline pat on subsequent calls) when no shell is available, or when iterating against an MCP client that doesn't expose terminal access to the agent.

Call the MCP server directly via HTTP

https://mcp.amba.dev/mcp is a plain Streamable-HTTP endpoint, not a stdio process — any agent with curl or fetch can call the full tool surface without configuring mcpServers in a host client at all. This is the path to use when:

  • You ran amba init and the MCP entry persisted, but the typed mcp__amba__* tools haven't loaded into your agent's tool list yet (e.g., Claude Code, Codex, Windsurf — they read mcpServers once at session startup).
  • You're driving Amba from a non-MCP-aware agent or a CI script.
  • You want the full 500+ tool surface without picking which subcommand the amba CLI exposes.

Wire shape — standard JSON-RPC 2.0 tools/call:

PAT=$(jq -r .pat ~/.amba/credentials.json)
curl -sS https://mcp.amba.dev/mcp \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "amba_currencies_create",
      "arguments": {
        "project_id": "proj_…",
        "name": "coins",
        "display_name": "Coins"
      }
    }
  }'

The response wraps the tool's actual payload at result.content[0].text as a JSON string:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [{ "type": "text", "text": "{\"data\":{\"id\":\"cur_…\", \"name\":\"coins\", …}}" }]
  }
}

Pre-auth tools (amba_developer_signup, amba_developer_login, amba_developer_refresh) work without the Authorization header — the rest require a Bearer (PAT or OAuth access token). Standard MCP methods (initialize, tools/list, ping) also work without a Bearer if you want to enumerate the catalog.

Manual setup

If your MCP client isn't in the list above (or you skipped the auto-write with --no-mcp-config), drop the snippet below into its config file.

Server URL: https://mcp.amba.dev/mcp

Mint a Bearer token at app.amba.dev/settings/api-keys, or run npx @layers/amba login to write one to ~/.amba/credentials.json.

Claude Code

Edit ~/.claude.json:

{
  "mcpServers": {
    "amba": {
      "type": "http",
      "url": "https://mcp.amba.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "amba": {
      "type": "http",
      "url": "https://mcp.amba.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "amba": {
      "type": "http",
      "url": "https://mcp.amba.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "amba": {
      "url": "https://mcp.amba.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

The new config takes effect the next time you launch the MCP client. (Claude Code, Codex, and Windsurf load mcpServers at startup; Cursor watches the file and picks up changes on the next message.)

Browser-only clients (Claude.ai web)

Claude.ai connectors use OAuth 2.1 + PKCE — there is no static Bearer to paste. When you add Amba as a connector, Claude.ai's MCP client:

  1. Discovers the authorization server at https://mcp.amba.dev/.well-known/oauth-authorization-server.
  2. Sends you to https://mcp.amba.dev/authorize to sign in with your Amba developer credentials (the same email + password you use for app.amba.dev).
  3. Exchanges the resulting one-time code for an access token at https://mcp.amba.dev/token, with PKCE (S256) enforced.
  4. Refreshes the access token automatically before it expires (1h access token, 30-day refresh).

To connect:

  1. In Claude.ai, open Settings → Connectors → Add custom connector.
  2. Server URL: https://mcp.amba.dev/mcp.
  3. Click Authorize. You'll be redirected to the Amba sign-in page; complete it and you'll return to Claude.ai with the connector active.

What the server publishes

The MCP server exposes the standard OAuth 2.1 surface for inspection:

  • GET /.well-known/oauth-authorization-server — RFC 8414 authorization-server metadata.
  • GET /.well-known/oauth-protected-resource — RFC 9728 protected-resource metadata.
  • GET /authorize — interactive consent (HTML form).
  • POST /token — code → access + refresh token; supports grant_type=refresh_token rotation.
  • GET /jwks — public RSA key (kid: amba-mcp-1) for verifying issued access tokens.

PKCE is mandatory — only code_challenge_method=S256 is accepted. The implicit, password, and client-credentials grants are not supported.

Authentication

The MCP middleware accepts either:

  • A Bearer token from amba_developer_signup / amba_developer_login / any PAT minted in the dashboard (used by Claude Code, Cursor, Windsurf, and the CLI).
  • An OAuth-issued access token from the flow above (used by Claude.ai web).

Both resolve to the same developer identity for downstream tool calls.

Verifying

After connecting, ask your agent:

List all my Amba projects.

If the agent calls amba_projects_list and returns your projects, you're connected. A 401 means the token is wrong, expired, or (for OAuth) failed signature verification; a MISSING_AUTHORIZATION means the header isn't being sent.

Previous

MCP Server

Next

Tools

On this page