---
title: MCP service accounts
description: "Authenticate an AI agent, bot, CI job, or backend service to Amplitude MCP using an org-owned service account and the OAuth 2.0 client credentials flow."
product: general
lang: en
last_updated: 2026-10-15
token_estimate: 2498
---
# MCP service accounts

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

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.

> **Note:**
>
> **Availability:** MCP service accounts are available to organizations on the Enterprise plan with MCP access enabled.

## When to use a service account instead of user OAuth

| Situation | Use | Why |
| --- | --- | --- |
| A person uses Claude, Cursor, ChatGPT, or another AI client | User OAuth | The agent acts as that person, with that person's permissions. |
| A shared bot, backend agent, MCP gateway, or scheduled job | MCP service account | No interactive login. You can scope it, rotate it, and revoke it independently, and it doesn't depend on any one person's account. |
| Sending event data | [SDK](https://amplitude.com/docs/sdks) or [HTTP V2 API](https://amplitude.com/docs/apis/analytics/http-v2) | MCP doesn't ingest events. |

## 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**.

> **Warning:** Save both credentials now
>
> Amplitude shows the client secret only once. Store it in your secret manager before dismissing the panel. If you lose it, use **Rotate** to generate replacement credentials.

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.

```shell
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.

> **Note:**
>
> **Match the account's scopes.** The Settings label `ALL_READ` corresponds to `all:read` in token requests. For an older account that lists `MCP_READ`, request `scope=mcp:read`. Always send an explicit scope that is allowed for that account.

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

```json
{
  "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

| Region | MCP server URL | Token endpoint |
| --- | --- | --- |
| United States (default) | `https://mcp.amplitude.com/mcp` | `https://mcp.amplitude.com/token` |
| EU residency | `https://mcp.eu.amplitude.com/mcp` | `https://mcp.eu.amplitude.com/token` |

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

## Scopes

| Settings label | OAuth scope | Allows |
| --- | --- | --- |
| `ALL_READ` | `all:read` | Read and query tools, subject to the account's project permissions. |

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.

| Symptom | What to check | Fix |
| --- | --- | --- |
| `invalid_client` when requesting a token | Incorrect credentials, wrong region, or the account was rotated or revoked | Check the region and both credential values. Send them as URL-encoded form fields, as shown in the token example. After rotation, use the new client ID and secret. |
| `invalid_scope` when requesting a token | The scope may be misspelled, malformed, or not allowed for the account | Use the scopes listed for that account. Older accounts may require `mcp:read` instead of `all:read`. |
| `invalid_token` or 401 on an MCP call | Token expired, wrong region, or the account was rotated or revoked | For an active account, request a new token with its current credentials from the correct regional endpoint and update the MCP header. A revoked account can't be reused. |
| Connected but no projects are listed | Account's project permissions and group memberships | Find **SA: <name>** in **Members & Groups** or **Members**, check its groups and project roles, then call `get_amplitude_context` again. |
| Tools are missing | Token scopes, connection options, and whether the tool is available for this client and organization | Request an explicit scope allowed for the account and update the client header. Customer accounts created through Settings are currently read-only. If expected read tools are still missing, check the client's tool-list or discovery settings and contact your Amplitude team to confirm availability. |
| **Service accounts** option isn't visible | Plan eligibility, MCP access, service-account enablement, and management permissions | Have an Org Admin check **Settings > Permissions**. Service accounts require both an Enterprise plan and MCP access enabled. If the option is still missing, contact your Amplitude team. |
| Create fails with a limit error | The org already has 10 active service accounts | Revoke unused service accounts. |