API Tokens

API tokens let you connect to Apps without a browser or interactive login. Use them in web agents, CI/CD pipelines, automated tests, and server-to-server integrations.

What are API tokens?

An API token is a long-lived credential you generate in the mctx dashboard. You include it in requests as a Bearer token and mctx authenticates you automatically — no OAuth browser flow needed.

Common use cases:

• Automated agents that call MCP tools on a schedule
• CI/CD pipelines that test or validate App responses
• Server-to-server integrations where no browser is available
• Headless scripts that need consistent, non-interactive access

How tokens differ from browser-based OAuth:

Creating a token

1. Open your subscriptions page and sign in.

2. Find the server you want to create a token for and click the key icon (tooltip: "API Tokens") in the subscription card's action row.

3. In the dialog that opens, click Create Token.

4. Fill in the token details:

   • Name — a descriptive label such as ci-pipeline or weather-agent-prod
   • Servers — the current server is pre-selected; you can add more servers you own or subscribe to
   • Expiration — choose 7, 30, or 90 days
   • IP allowlist (optional) — one or more IP addresses or CIDR ranges that may use this token

5. Click Generate.

Your token starts with mctx_ and is 48 characters long. Store it somewhere safe before continuing.

Using a token

Include the token as a Bearer credential in the Authorization header of every request.

curl example

curl -X POST https://my-app.mctx.ai/v1 \
  -H 'Authorization: Bearer mctx_your_token_here' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

HTTP header format

Authorization: Bearer mctx_your_token_here

SDK / client config

If your MCP client supports a headers or authorization option, pass the token directly:

const client = new MCPClient({
  serverUrl: "https://my-app.mctx.ai/v1",
  headers: {
    Authorization: `Bearer ${process.env.MCTX_API_TOKEN}`,
  },
});

Always read the token from an environment variable or secret store — never hardcode it in source files.

Rotating a token

Token rotation replaces the secret value of an existing token in-place. The token ID, name, scopes, expiration date, and IP allowlist stay the same. Only the secret changes. The old secret is invalidated immediately.

Use the rotate endpoint when:

• Your CI/CD system rotates credentials on a schedule
• A token may have been exposed and you need to replace it without reconfiguring everything
• You want to replace a token value without touching its configuration

Rotation via Bearer auth

Send a POST request to the rotate endpoint using the current token as Bearer auth. The token authenticates the rotation request — no session cookie or CSRF token is required.

curl -X POST https://api.mctx.ai/api/tokens/{token-id}/rotate \
  -H 'Authorization: Bearer mctx_your_current_token_here'

The response returns the new token value. Copy it immediately — it is shown only once.

{
  "token": "mctx_new_token_value_here",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "ci-pipeline",
  "prefix": "mctx_new_tok",
  "expires_at": "2026-06-18T12:00:00.000Z",
  "allowed_ips": null,
  "scopes": [
    {
      "server_id": "abc123",
      "server_name": "My App",
      "server_slug": "my-app"
    }
  ],
  "created_at": "2026-03-20T12:00:00.000Z"
}

How to rotate in a CI/CD pipeline

This pattern lets a CI job replace its own token on every run, keeping the credential fresh without any manual intervention.

Step 1: Store the token and its ID as CI secrets.

You need both the token value (for authentication) and the token ID (for the rotation request URL). Store them as separate secrets in your CI/CD system.

Step 2: Add a rotation step to your pipeline.

#!/bin/bash
set -euo pipefail

# Rotate the token — the token authenticates itself
RESPONSE=$(curl --silent --fail \
  -X POST "https://api.mctx.ai/api/tokens/${MCTX_TOKEN_ID}/rotate" \
  -H "Authorization: Bearer ${MCTX_API_TOKEN}")

# Extract the new token value
NEW_TOKEN=$(echo "$RESPONSE" | jq -r '.token')

# Update the CI secret with the new value before proceeding
# (how to do this depends on your CI provider — see examples below)
echo "Rotation complete. Update MCTX_API_TOKEN with the new value."
echo "$NEW_TOKEN"

GitHub Actions — rotate and update the secret programmatically:

# Rotate the token
RESPONSE=$(curl --silent --fail \
  -X POST "https://api.mctx.ai/api/tokens/${MCTX_TOKEN_ID}/rotate" \
  -H "Authorization: Bearer ${MCTX_API_TOKEN}")

NEW_TOKEN=$(echo "$RESPONSE" | jq -r '.token')

# Update the GitHub Actions secret via the GitHub API
# Requires a GitHub token with secrets:write permission
gh secret set MCTX_API_TOKEN --body "$NEW_TOKEN"

Step 3: Use the new token for the rest of the pipeline.

After rotation, use the new token value for any subsequent MCP requests in the same run. The old token stops working immediately after rotation.

What rotation does and does not change

Rotation does not extend the expiration date. If you need a longer-lived token, edit the expiration separately from the dashboard or via PATCH /api/tokens/:id.

Session-authenticated rotation

If you are authenticated via the dashboard (session cookie), you can rotate any of your own tokens by their ID:

# Session auth (cookie-based) — rotate any token you own
curl -X POST https://api.mctx.ai/api/tokens/{token-id}/rotate \
  -H 'Cookie: your-session-cookie'

This is the same endpoint. The difference is that session auth lets you rotate any token you own, while Bearer auth lets a token rotate only itself.

Security best practices

Store tokens as secrets

Never commit a token to source control. Use environment variables, CI secret stores, or a secrets manager instead.

# Set as an environment variable
export MCTX_API_TOKEN=mctx_your_token_here

# Reference it in scripts
curl -H "Authorization: Bearer $MCTX_API_TOKEN" https://my-app.mctx.ai/v1

In CI/CD systems (GitHub Actions, GitLab CI, etc.), store the token as an encrypted secret and inject it at runtime. Never print it in logs.

Use IP allowlists for CI/CD tokens

When a token is used from a fixed IP range — such as a CI runner or a VPC — add that range to the token's IP allowlist. This limits the damage if the token is ever exposed.

Set the allowlist when you create the token, or edit it later from Developer Settings → API Tokens.

Scope tokens to only the servers they need

Select the minimum set of servers when creating a token. A token scoped to one server cannot access others, even if you subscribe to them.

Rotate tokens before expiry

The fastest approach is to use the rotate endpoint. A single request replaces the secret, keeps all configuration intact, and immediately invalidates the old value.

curl -X POST https://api.mctx.ai/api/tokens/{token-id}/rotate \
  -H 'Authorization: Bearer mctx_your_current_token_here'

If you prefer to create a completely new token (for example, to change the scope or expiration at the same time):

1. Create a new token with the desired scope and allowlist.
2. Deploy the new token to your system.
3. Verify the new token works.
4. Revoke the old token from Developer Settings → API Tokens.

This approach keeps your access uninterrupted when you need to change more than just the secret.

Maximum 90-day expiration

mctx does not issue tokens that never expire. The maximum lifetime is 90 days. Set a calendar reminder to rotate tokens before they expire — expired tokens return 401 Unauthorized immediately.

Managing tokens

View active tokens

Go to Developer Settings → API Tokens to see all active tokens. Each token shows:

• Name and prefix (first characters only)
• Which servers it can access
• Expiration date
• Last used date

Edit a token

Click the token name to edit its name, expiration date, or IP allowlist. You cannot change the servers a token can access after creation — create a new token instead.

Revoke a token

Click Revoke next to the token. Revocation takes effect within 10 minutes due to edge caching. After that window, requests using the revoked token return 401 Unauthorized.

Revoking is permanent. If you need access again, create a new token.

Token format

Tokens follow a consistent format that enables automated detection:

• Prefix: mctx_
• Total length: 48 characters

The mctx_ prefix allows secret scanning tools (GitHub Secret Scanning, GitLab secret detection, custom scanners) to identify exposed tokens automatically. If a token appears in logs, a pull request diff, or any public location, revoke it immediately and create a new one.

Error responses

401 Unauthorized

Your token is missing, malformed, expired, or revoked.

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Unauthorized"
  },
  "id": null
}

Check that the Authorization header is present and formatted as Bearer mctx_.... If the token expired, create a new one.

403 Forbidden

Your token is valid but not scoped to the server you are trying to access.

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32003,
    "message": "Forbidden"
  },
  "id": null
}

Create a new token that includes the target server in its scope.

403 IP Not Allowed

Your request came from an IP address outside the token's allowlist.

Update the allowlist in Developer Settings → API Tokens, or make the request from an allowed address.

Related documentation

• How Authentication Works — OAuth 2.0 details for MCP clients
• FAQ — Common issues and solutions
• Platform Requirements — Rate limits and connection constraints

See something wrong? Report it or suggest an improvement — your feedback helps make these docs better.