Authentication
The MCP server supports two authentication methods. Choose the one that fits your workflow.
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 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.
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, 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 instead. Gemini CLI still uses this helper.
Write a version in the config. Use mcp-remote@0.2.5.
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 connects over HTTP. It does not use mcp-remote. See Claude and Gemini CLI for the full config.
If two login tabs open, see Troubleshooting.
API key
API keys are generated from Config > PLATFORM > API Keys in your Ada dashboard. See 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.
Permissions
Tool access is governed by your Ada dashboard role:
edit_agent_behavior and 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.