Install

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

npx @layers/amba init --sandbox

amba init --sandbox 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, and merges an amba entry into every MCP client config it finds on disk.

✓ Sandbox account provisioned (sandbox-1747234567-abc123@layers.com)
✓ Project created: proj_abc123
✓ Credentials saved to ~/.amba/credentials.json
✓ .env.local updated with AMBA_PROJECT_ID + AMBA_CLIENT_KEY + AMBA_API_URL
✓ AMBA.md written (sandbox guide)
✓ MCP config updated: ~/.claude.json (entry: 'amba')
✓ MCP config updated: ~/.cursor/mcp.json (entry: 'amba')

Next:
  → npm install @layers/amba-web
  → Initialize the SDK in your app entry: Amba.configure({ projectId: process.env.AMBA_PROJECT_ID, clientKey: process.env.AMBA_CLIENT_KEY })

Done. Restart your MCP client so it loads the Amba MCP server:
  • Claude Code: Cmd+Q, then reopen
  • Cursor: Cmd+Q, then reopen

After the restart, re-ask the original question — Amba's MCP toolset will be available.

Sandbox limits: 100 MAU, 10 MB DB. Verify your email in the console to upgrade to Free.

After the command exits, restart your MCP client (quit + reopen) so it re-reads the config file. The Amba tools then appear in the tool picker.

What the CLI configures

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

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 email
amba init --sandbox --no-mcp-config          # skip the config-write step
amba init --sandbox --json                   # machine-readable summary for agents

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": "Write the matching snippet from `mcp_config` to the customer's MCP client config file (merge with existing `mcpServers` — do not overwrite). After writing, prompt the customer to restart their MCP client to load the Amba credential."
}

The agent merges the matching snippet into the customer's MCP config (preserving any other mcpServers.* entries), then prompts the customer to restart their MCP client. On restart the PAT is sent as the inbound Bearer and every Amba MCP tool call works.

amba_developer_login returns the same mcp_config shape for returning customers.

Headless verification

The sandbox project ships with a 50-MAU cap until the developer is verified. To lift the cap without bouncing the customer through a browser, call amba_developer_verify with the verify_token from the signup response:

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

Restart cycle

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

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" }
    }
  }
}

Restart the client after editing.

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.