> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Authentication

The MCP server supports two authentication methods. Choose the one that fits your workflow.

| Method                  | MCP Server URL                                     | Best for                                 |
| ----------------------- | -------------------------------------------------- | ---------------------------------------- |
| **OAuth** (recommended) | `https://<your-ada-instance-domain>/api/mcp/oauth` | Interactive use with browser-based login |
| **API Key**             | `https://<your-ada-instance-domain>/api/mcp`       | Automated setups or programmatic access  |

## Ada instance domain

Your Ada instance domain is the URL you use to log in to your Ada dashboard (for example, `acme-corp.ada.support`, `acme-corp.eu.ada.support`, or `acme-corp.maple.ada.support`).

If you log in at `https://acme-corp.eu.ada.support`, your MCP Server URL is `https://acme-corp.eu.ada.support/api/mcp/oauth` for OAuth or `https://acme-corp.eu.ada.support/api/mcp` for API key.

## Connect Claude

Add Ada as a custom connector in Claude. This is the recommended path for Claude Desktop, claude.ai, and Cowork. You do not need Node.js. You do not need `mcp-remote`.

Use this URL:

`https://<your-ada-instance-domain>/api/mcp/oauth`

See [Claude](/mcp/introduction/getting-started/claude) for the full steps.

### Who can add the connector

On a Free, Pro, or Max plan, you add the connector yourself.

On a Team or Enterprise plan, a Claude organization Owner or Primary Owner must add the connector first. Other members cannot paste the Ada URL themselves. After the Owner adds it, each member clicks **Connect**. Each member logs in with their own Ada account.

### If you cannot add a custom connector

Use the local helper `mcp-remote`. Pin the helper version. See [Pin the local helper version](#pin-the-local-helper-version).

## OAuth

OAuth uses browser-based login with your Ada credentials. No API key is required, and no secrets are stored in configuration files.

Use OAuth when:

* Connecting an interactive AI assistant (Claude, ChatGPT, Codex CLI, Gemini CLI).
* You want access tied to an individual user account.
* You want to avoid distributing long-lived credentials.

## Pin the local helper version

Use `mcp-remote` only when a client cannot add Ada as a remote MCP URL. Claude Desktop should use a [custom connector](#connect-claude) instead. Gemini CLI still uses this helper.

Write a version in the config. Use `mcp-remote@0.2.5`.

```json
"args": ["mcp-remote@0.2.5", "https://acme-corp.ada.support/api/mcp/oauth"]
```

Do not write `mcp-remote` without a version. If you omit the version, `npx` installs the newest helper on each start. A new helper version stores login data in a new folder. You must log in again.

Claude Code and Codex CLI connect over HTTP. They do not use `mcp-remote`. See [Claude](/mcp/introduction/getting-started/claude) and [Codex CLI](/mcp/introduction/getting-started/codex-cli) for the full HTTP config. See [Gemini CLI](/mcp/introduction/getting-started/gemini-cli) for the full helper config.

If two login tabs open, see [Troubleshooting](/mcp/introduction/troubleshooting#two-login-tabs-in-claude-desktop).

## API key

API keys are generated from **Config > PLATFORM > API Keys** in your Ada dashboard. See [Authentication](/reference/introduction/authentication) for details on key management.

Use an API key when:

* Running MCP clients in non-interactive environments (CI pipelines, scheduled jobs, backends).
* Integrating programmatically with the Google Agent Development Kit (ADK).
* Browser-based login is not available.
* You manage more than one AI Agent.

When you connect more than one AI Agent, an API key is the preferred method. See [Connecting multiple Agents](/mcp/introduction/getting-started/connecting-multiple-agents).

> **Tip**
>
> For security, store the API key as an environment variable rather than pasting it into configuration files.

## Permissions

Tool access is governed by your Ada dashboard role:

| Ada role  | MCP access                  |
| --------- | --------------------------- |
| Owner     | All tools, including writes |
| Admin     | All tools, including writes |
| Agent     | Read-only tools             |
| Read Only | Read-only tools             |

[`edit_agent_behavior`](/mcp/tools/edit-agent-behavior) and [`edit_agent_config`](/mcp/tools/edit-agent-config) are the write tools. Calling a write tool as an Agent or Read Only user returns a permission error, and write tools are hidden from the assistant's tool list for those roles.

Role changes apply on the next tool call — no reconnect required.

Role-based access applies to OAuth only. API key requests use a separate auth path scoped by the key's permissions.