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, Codex CLI, Gemini CLI, Microsoft Copilot).
- 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 and Codex CLI connect over HTTP. They do not use mcp-remote. See Claude and Codex CLI for the full HTTP config. See Gemini CLI for the full helper 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.
With individual settings enabled, new API keys have no MCP tools until an Owner allows them. Existing dashboard keys keep global access until restricted. See Tool permissions before changing an integration.
API keys can also connect more than one AI Agent. See Connecting multiple Agents.
Permissions
For OAuth connections, your dashboard role sets the maximum tool access:
Write tools include configuration changes, change set promotion and reverts, code execution, simulations, and MCP server management. These tools can change the AI Agent or connected systems. Members with the Agent or Read Only role cannot see or call write tools.
Global settings limit everyone, including Owners and API keys. Individual settings can further limit non-Owner members and keys. They cannot allow tools blocked globally or by a member’s role.
Role changes apply on the next tool call. You do not need to reconnect.
Dashboard role limits apply to OAuth only. A valid key with Platform APIs access can connect to MCP. Its allowed MCP tools follow global settings and any individual key restrictions. API keys do not inherit the creator’s role or personal MCP restrictions. Anyone with the key can use its allowed tools.