MCP server

Authalla exposes a Model Context Protocol (MCP) server that lets AI assistants manage your tenants, users, apps, branding, domains, and more — directly from your editor or chat.

Connect your agent to your Authalla account and it can do everything the admin dashboard can.

Quick start

Add the Authalla MCP server URL to your client:

https://api.authalla.com/mcp

That's it. Your MCP client signs you in through your browser, you approve the connection on a consent screen, and if you belong to more than one Authalla account you pick the one the agent should manage. No API keys, no client registration.

Setup for Claude Code

Add the MCP server with a single command:

claude mcp add --transport http authalla https://api.authalla.com/mcp

Then sign in:

claude mcp login authalla

Claude Code discovers the authorization server from https://api.authalla.com/.well-known/oauth-protected-resource/mcp, opens your browser, and identifies itself with its Client ID Metadata Document. Once connected, you can ask Claude to manage your account directly:

> Create a new app called "my-app" with redirect URI http://localhost:3000/callback
> Update the login page theme to use dark blue as the brand color
> Add a custom domain app.example.com to my tenant

Setup for Claude Desktop and claude.ai

1. Open Settings > Connectors and add a custom connector with the URL:

https://api.authalla.com/mcp

2. Claude opens your browser to sign in to Authalla and approve the connection
3. Once connected, the Authalla tools appear in the tools menu

Setup for Cursor and VS Code

Cursor and VS Code do not yet identify themselves with a Client ID Metadata Document, so they cannot use the automatic sign-in above. Use an account API key instead:

{
  "mcpServers": {
    "authalla": {
      "url": "https://api.authalla.com/mcp",
      "headers": {
        "Authorization": "Bearer authalla_ak_<keyid>_<secret>"
      }
    }
  }
}

For VS Code put the same block under "mcp": { "servers": { ... } } in settings.json or .vscode/mcp.json.

Connecting with an account API key

Any MCP client can skip the browser flow and authenticate with an account API key sent as a bearer token. This is the right choice for CI pipelines, shared automation, and clients without OAuth support:

claude mcp add --transport http authalla https://api.authalla.com/mcp \
  --header "Authorization: Bearer authalla_ak_<keyid>_<secret>"

The connection is bound to the key's account and limited to the key's scopes and tenant allowlist. Changes the agent makes are recorded in Team activity under the key, not a person, so prefer the interactive sign-in for day-to-day work: then they name the team member who connected the agent.

How authentication works

The MCP server follows the MCP authorization specification (OAuth 2.1). When a client connects for the first time it:

1. Gets a 401 whose WWW-Authenticate header points at https://api.authalla.com/.well-known/oauth-protected-resource/mcp, and fetches that document to discover the authorization server (login.authalla.com) and the scopes to request.
2. Identifies itself with an OAuth Client ID Metadata Document: its client_id is an https URL pointing at a JSON document that describes the client and its redirect URIs. Authalla fetches and validates the document; nothing is registered by hand. Dynamic Client Registration is not supported.
3. Opens your browser to sign in with your Authalla account (passkey, magic link, or social login).
4. Shows a consent screen naming the client and the permissions it asked for, with a note that the client registered itself, so its name hasn't been verified, and, for an agent such as Claude Code, that it runs on your computer. The MCP server asks for the authalla:manage permission, which the screen calls out in bold: it lets the agent do everything you can do in the admin dashboard, acting as you. Agents that identify themselves this way always go through consent, even if you approved them before.
5. If you belong to several Authalla accounts, asks which account the agent may manage. The choice is baked into the token; get_me shows it and you reconnect to switch.
6. Receives an access token issued for https://api.authalla.com/mcp (the token's audience) carrying the authalla:manage scope, and a refresh token. The MCP server accepts a token only when both the audience and that scope are present. Tokens are refreshed automatically.

To revoke an agent, sign out of it in your MCP client; the refresh token stops being renewed. Account API keys are revoked from Settings → API Keys.

Available tools

The MCP server exposes the following tools for managing your Authalla account:

Account and session

Tenants

Users

The user tools need an interactive sign-in: account API keys don't carry the users:read and users:write scopes.

Apps

An app is what the OAuth2 specs call a client. These tools take the app's ID as app_id; it is the same value as the app's client_id.

Branding

Custom domains

Sender addresses

Sender addresses belong to the account, so all but set_tenant_sender_address need an account-wide key.

Social login

Each social login belongs to one tenant, with at most one per provider.

Resource servers

Your own APIs and MCP servers that the tenant issues access tokens for. See Build an MCP server with Authalla.

Organizations

Your business customers, each with its email domains, its enterprise connection, its SCIM provisioning, its members and the setup link its IT admin uses to connect their identity provider. See Single sign-on, SCIM provisioning and the setup portal.

Team

These tools need an interactive sign-in; an account API key cannot use them, so a key can never add an admin to the account.

Multiple accounts and tenants

If you belong to several Authalla accounts, the consent screen asks which one the agent may manage, and the connection is bound to it. Connect a second time (for example under a different server name in Claude Code) to give an agent access to another account.

Tools that operate on a specific tenant accept an optional tenant_id parameter. If the account has only one tenant, it is selected automatically; otherwise call select_tenant once or pass tenant_id on each call. Use get_me to see the tenants.

Programmatic access (without MCP)

The MCP server is for AI assistants. For automated pipelines or custom integrations, call Authalla's REST APIs directly, from your server or CI. Each takes its own secret credential:

• Management API (control plane) — provision and configure infrastructure across your whole account: tenants and their allowed origins, apps, custom domains, sender addresses, social logins, resource servers, organizations, and themes. Authenticated with an account API key (authalla_ak_...) created from the Admin Dashboard. This is the equivalent of what the MCP tools above do, and the same key also works on the MCP endpoint.

  curl https://api.authalla.com/management/v1/tenants \
    -H "Authorization: Bearer authalla_ak_<keyid>_<secret>"
  

• Application API (data plane) — manage users within a single tenant at runtime. Authenticated with a tenant-bound OAuth2 client credentials token. Create a Backend Service app in the Admin Dashboard and use the client credentials grant:

  curl -X POST https://your-tenant.authalla.com/oauth2/token \
    -d "grant_type=client_credentials" \
    -d "client_id=YOUR_CLIENT_ID" \
    -d "client_secret=YOUR_CLIENT_SECRET" \
    -d "scope=users:read users:write"
  

Tenant client_credentials tokens are scoped to the data plane (users:read / users:write) and are not accepted by the MCP endpoint — account-wide configuration goes through the Management API account key or the MCP server. Neither secret credential belongs in a browser or a mobile app. A signed-in user's own profile, sessions and connected apps are the User API's job, with the user's own access token; see Choosing an API.