Skip to navigation

Authentication

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

MethodMCP Server URLBest for
OAuth (recommended)https://<your-ada-instance-domain>/api/mcp/oauthInteractive use with browser-based login
API Keyhttps://<your-ada-instance-domain>/api/mcpAutomated 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 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.

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

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

Permissions

For OAuth connections, your dashboard role sets the maximum tool access:

Ada roleMCP access
OwnerRead and write tools
AdminRead and write tools
AgentRead-only tools
Read OnlyRead-only tools

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.