MCP service accounts

Use an MCP service account when an AI agent, bot, CI job, or backend service needs to call Amplitude MCP with no person at a browser to complete an OAuth login. A service account is an org-owned identity with its own client ID and client secret. Your service exchanges those credentials for a short-lived access token with the OAuth 2.0 client credentials flow, then sends that token to the MCP server.

When to use a service account instead of user OAuth

Prerequisites

• Have an Org Admin complete setup. Org Admins can manage service accounts by default.
• Your organization is on the Enterprise plan and has MCP access enabled.
• If Service accounts is missing from Settings, contact your Amplitude team to confirm enablement for your organization.
• Your MCP client or service supports remote MCP over Streamable HTTP and lets you set a custom Authorization header.
• Your service can request a new access token and update the client's authorization header before the current token expires.

Create a service account

1. In Amplitude, go to Settings > Permissions > Service accounts.
2. Click Create service account.
3. Enter a descriptive name, for example support-bot-prod.
4. The account includes read access, shown as ALL_READ. Customer accounts created through Settings are currently read-only.
5. If your organization uses permission groups, select the groups that grant access to the projects the service needs. You can also assign groups later in Members & Groups.
6. Click Create, then copy the client ID and client secret.

You don't need a personal access token (PAT) to create a service account through Settings.

Assign roles and permissions

New service accounts are created as Members. They don't inherit the creating admin's permissions. Their project and data access depends on your organization's roles and permission groups.

1. Open Settings > Permissions > Members & Groups (or Members if your organization doesn't use groups).
2. Find the account named SA: <name>, for example SA: support-bot-prod.
3. Assign permission groups or project roles that grant the data access this service needs, as you would for a member. If you need a custom role, define it in Role Management, then assign it to the account or its group.
4. After connecting, call get_amplitude_context with no arguments and check the returned project list.

OAuth scopes limit which kinds of tools an account can use. Project roles and permissions control which project data those tools can access. Review both before sharing the credentials with an automated service.

Get an access token

Exchange the client ID and secret at the token endpoint for your region. Replace the placeholders with the credentials from Settings.

curl -X POST https://mcp.amplitude.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=CLIENT_ID" \
  --data-urlencode "client_secret=CLIENT_SECRET" \
  --data-urlencode "scope=all:read"

Read access_token and expires_in from the response. expires_in is the token lifetime in seconds. Request a new token with the same client credentials before it expires, allowing a small margin for network delays.

Connect an agent or MCP client

Send the access_token, rather than the client secret, as a Bearer token on every MCP request. The following example is for clients that accept an mcpServers configuration with custom headers. Check your client's documentation for its exact format.

{
  "mcpServers": {
    "amplitude": {
      "url": "https://mcp.amplitude.com/mcp",
      "headers": {
        "Authorization": "Bearer ACCESS_TOKEN"
      }
    }
  }
}

Replace ACCESS_TOKEN with the token from the response. Before it expires, repeat the client credentials exchange and update the header your MCP client sends. A static configuration doesn't renew tokens automatically. Reload or reconnect the client if needed to apply the new token.

To verify the connection, call get_amplitude_context with no arguments ({}). It should return your organization and the projects the service account can access.

Regions

Use the endpoints that match your organization's data region for both token requests and MCP calls.

Scopes

Service accounts created through Settings provide read access.

New service accounts use all:read. Older accounts retain mcp:read, including when rotated. Both scopes authorize the same read tools, subject to project permissions. Use the scope listed for your account when requesting a token. Existing service accounts don't need to be recreated in Settings.

Rotate or revoke credentials

• Rotate: In Service accounts, click Rotate on the account's row and confirm. Rotation creates a replacement account with a new client ID and client secret, then revokes the old account. Save both new values, update every client, and request a new access token. There is no grace period for the old credentials or tokens. Verify project access after switching.
• Revoke: Click Revoke on the account's row and confirm. This permanently disables the account. Subsequent MCP requests using its tokens are rejected. The account remains listed with a Revoked status.
• Each organization can have up to 10 active service accounts. Revoke unused accounts to free a slot.

For a planned cutover, create a separate account, assign and verify its permissions, update your service, then revoke the old account. This requires an available account slot.

Security best practices

• Grant access only to the projects and data the service needs.
• Create one service account per agent or environment so you can revoke one without breaking others.
• Store client secrets and access tokens in a secret manager. Never commit them or paste them into prompts.
• Rotate credentials regularly and when someone with access leaves. Plan the client update before rotating.
• Review service accounts periodically and revoke unused ones.

Troubleshooting

For token requests, read the response's error and error_description. An error code alone doesn't identify the exact cause.