> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ampup.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server Authentication

> How AmpUp's MCP server authenticates AI assistants with OAuth 2.1

The AmpUp MCP server lets AI assistants — Claude, Cursor, Windsurf, and any
other MCP-compatible client — call AmpUp tools on your behalf. This page
covers how that authentication is secured.

For end-user setup steps, see the [MCP integration guide](/integrations/claude-mcp).

## Two ways to connect

| Mode          | Used by                                                                              | Credential                                  | Best for                        |
| ------------- | ------------------------------------------------------------------------------------ | ------------------------------------------- | ------------------------------- |
| **OAuth 2.1** | Claude Code, claude.ai, Claude Desktop, Codex, Cursor, and most MCP-aware connectors | Short-lived JWT, refreshable                | End users — no API key handling |
| **API key**   | Clients that don't support OAuth (config-file flow)                                  | Long-lived bearer token from your dashboard | Developer / power-user setups   |

Both paths land at the same access-control layer: each request runs in your
AmpUp org, scoped to your user, with the same permissions you have in the
product UI.

## OAuth 2.1 flow

When a user clicks **Connect** in their MCP client:

<Steps>
  <Step title="The MCP client registers itself">
    The client uses **OAuth 2.1 Dynamic Client Registration** to register
    with AmpUp. Only redirect URIs belonging to known MCP clients (e.g.
    `https://claude.ai/api/mcp/auth_callback`) are accepted.
  </Step>

  <Step title="The user is redirected to AmpUp login">
    The MCP client opens AmpUp's authorization endpoint with a
    **PKCE S256 code challenge**. AmpUp redirects the user to the standard
    AmpUp login page.
  </Step>

  <Step title="The user authenticates with their existing AmpUp credentials">
    Login uses the same path as the AmpUp web app — Google, email/password,
    or your enterprise [SSO](/security/sso) connection. **MFA enforced by
    your IdP applies here**: if your org requires MFA, the user is
    challenged before the MCP token is issued.
  </Step>

  <Step title="An authorization code is returned to the MCP client">
    The MCP client exchanges the code (with the PKCE verifier) for an
    access token and refresh token.
  </Step>

  <Step title="Subsequent MCP requests use the access token">
    Every tool call from the assistant carries the bearer token, which
    AmpUp validates on each request.
  </Step>
</Steps>

The AI assistant **never sees the user's password** at any stage.

## Token lifetimes

| Token              | Lifetime  | Notes                                       |
| ------------------ | --------- | ------------------------------------------- |
| Authorization code | 5 minutes | Single-use, bound to client + PKCE verifier |
| Access token       | 1 hour    | Bearer JWT                                  |
| Refresh token      | 30 days   | Used to mint new access tokens              |

Refresh tokens are revoked automatically when:

* The user explicitly disconnects AmpUp from their MCP client.
* The token is revoked by an admin (token revocation is supported).
* 30 days elapse without use.

## Scopes and permissions

Issued tokens carry one of two scopes:

* `read` — read-only AmpUp tools (search, fetch, list).
* `write` — create / update / sync tools (create deals, push to CRM,
  upload recordings).

In MCP-aware clients (e.g. claude.ai), users see a **per-tool permission
panel** during connection setup. Read-only tools are enabled by default;
write tools must be explicitly approved before the assistant can call them.

Independent of OAuth scopes, **the MCP server enforces your in-product
roles**. A user with `viewer` role in AmpUp cannot use a write tool even if
the `write` scope is granted to the client — the action is rejected at the
server.

## Tenant isolation

Every MCP request is scoped to the org the authenticated user belongs to.
The MCP server resolves `org_id` and `user_id` from the validated token on
every request and applies them to all downstream queries — there is no path
for a user authenticated against one org to read data from another.

## Disconnecting

To revoke an MCP client's access:

* **From the MCP client**: remove AmpUp from your MCP connector / settings.
  This calls AmpUp's revocation endpoint and invalidates the refresh token
  immediately.
* **From AmpUp**: contact your admin or [support@ampup.ai](mailto:support@ampup.ai)
  to revoke a specific user's MCP tokens server-side.

In both cases, in-flight access tokens stop working at the next refresh
attempt; the longest residual access window is the remaining access-token
lifetime (≤ 1 hour).

## API key mode (developer flow)

Clients that don't support OAuth can consume the MCP server through a config
file with a long-lived bearer token:

```json theme={null}
{
  "mcpServers": {
    "ampup": {
      "url": "https://app.ampup.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk-a79-YOUR_API_KEY"
      }
    }
  }
}
```

API keys:

* Are generated in **Settings → API Keys** in the AmpUp dashboard.
* Inherit the role and permissions of the user who created them.
* Should be treated as secrets — store in a credential manager, never
  commit to source control.
* Can be revoked at any time from the same Settings page; revocation takes
  effect immediately.

For team or production use, prefer the OAuth flow — it gives end users a
clear consent screen, cleaner per-user attribution in audit logs, and
automatic token rotation.

## Logging and audit

Each MCP authentication event (login, token issuance, refresh, revocation)
is logged on the AmpUp side. Tool invocations are logged at the request
level with the resolved `user_id` and `org_id` so admins can attribute
agent actions back to the user who authorized the connection.

## Need help?

For MCP authentication questions, contact your AmpUp account team or
email [support@ampup.ai](mailto:support@ampup.ai).