MCP Access Tokens

MCP Access Tokens (PATs) let you authenticate against the AgentArea MCP proxy from any MCP client — Cursor, Claude Desktop, or your own tooling — without exposing your primary credentials.

Overview

AgentArea’s MCP proxy sits in front of every managed MCP server instance in your workspace. To connect an external client, you need a Personal Access Token (PAT) — a long-lived, revocable credential scoped to your workspace.

Workspace-Scoped

A single token grants access to every MCP instance in your workspace

Hash-Only Storage

Raw tokens are shown once at creation. Only a SHA-256 hash is ever persisted

Instant Revocation

Revoke a token immediately from the API or dashboard — no propagation delay

Token Format

Every PAT follows a predictable, identifiable structure:

aat_AbCdEfGhIjKlMnOpQrStUvWxYz012345678901234

Part	Value	Description
Prefix	`aat_`	AgentArea Token — identifies token type at a glance
Body	43 characters	32 random bytes encoded as URL-safe base64
Total length	47 characters	Fixed-length, suitable for validation

The first 12 characters after aat_ (e.g. aat_AbCdEfGh) are stored as token_prefix and displayed in the dashboard so you can identify tokens without storing the raw value.

Lifecycle

API Reference

Base path: /v1/mcp-access-tokens

Create Token
List Tokens
Get Token
Revoke Token

POST /v1/mcp-access-tokens
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "name": "cursor-dev-machine",
  "expires_in_days": 90
}

Response — the raw token is returned exactly once:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "cursor-dev-machine",
  "token": "aat_AbCdEfGhIjKlMnOpQrStUvWxYz012345678901234",
  "token_prefix": "aat_AbCdEfGh",
  "is_active": true,
  "expires_at": "2026-06-09T00:00:00Z",
  "access_count": 0,
  "last_accessed_at": null,
  "created_at": "2026-03-09T12:00:00Z"
}

Copy the token value immediately. It will never be shown again. If lost, revoke the token and create a new one.

GET /v1/mcp-access-tokens
Authorization: Bearer <session-token>

Response — raw tokens are never included in list responses:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "cursor-dev-machine",
    "token_prefix": "aat_AbCdEfGh",
    "is_active": true,
    "expires_at": "2026-06-09T00:00:00Z",
    "access_count": 142,
    "last_accessed_at": "2026-03-09T11:58:00Z",
    "created_at": "2026-03-09T12:00:00Z"
  }
]

GET /v1/mcp-access-tokens/{id}
Authorization: Bearer <session-token>

Returns full token details (excluding raw token and hash).

DELETE /v1/mcp-access-tokens/{id}
Authorization: Bearer <session-token>

Sets is_active = false immediately. Any in-flight requests using the token will be rejected on the next validation check.Response: 204 No Content

Using Tokens with MCP Clients

Cursor
Claude Desktop
HTTP / curl

Add the following to your Cursor MCP configuration (~/.cursor/mcp.json or the project-level .cursor/mcp.json):

{
  "mcpServers": {
    "my-agentarea-tool": {
      "url": "https://<your-domain>/mcp/<instance-id>/sse",
      "headers": {
        "Authorization": "Bearer aat_AbCdEfGhIjKlMnOpQrStUvWxYz012345678901234"
      }
    }
  }
}

Use a project-level config file so each project can reference a different MCP instance while sharing a single workspace token.

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on your OS:

{
  "mcpServers": {
    "my-agentarea-tool": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "MCP_SERVER_URL": "https://<your-domain>/mcp/<instance-id>",
        "MCP_AUTH_TOKEN": "aat_AbCdEfGhIjKlMnOpQrStUvWxYz012345678901234"
      }
    }
  }
}

Or, for SSE-native clients that accept raw headers:

{
  "mcpServers": {
    "my-agentarea-tool": {
      "url": "https://<your-domain>/mcp/<instance-id>/sse",
      "headers": {
        "Authorization": "Bearer aat_AbCdEfGhIjKlMnOpQrStUvWxYz012345678901234"
      }
    }
  }
}

For direct API testing or custom integrations, pass the token as a standard Bearer header:

curl -N \
  -H "Authorization: Bearer aat_AbCdEfGhIjKlMnOpQrStUvWxYz012345678901234" \
  -H "Accept: text/event-stream" \
  "https://<your-domain>/mcp/<instance-id>/sse"

For JSON-RPC style MCP:

curl -X POST \
  -H "Authorization: Bearer aat_AbCdEfGhIjKlMnOpQrStUvWxYz012345678901234" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  "https://<your-domain>/mcp/<instance-id>"

Creating Your First Token

Open the MCP Servers dashboard

Navigate to MCP Servers in the AgentArea dashboard and select the instance you want to connect to.

Go to Access Tokens

Click the Access Tokens tab on the instance detail page, then click New Token.

Name and configure the token

Give the token a descriptive name that identifies the client or machine it will be used on (e.g. cursor-laptop, ci-pipeline). Set an expiry appropriate for the use case.

Name:        cursor-laptop
Expires in:  90 days

Copy the raw token

The dashboard displays the full token value exactly once. Copy it now and store it in a password manager or secrets vault.

If you navigate away without copying the token, you must revoke it and create a new one. The raw token cannot be recovered.

Configure your MCP client

Paste the token into your client’s configuration as shown in the Using Tokens section above.

Token Fields Reference

Field	Type	Description
`id`	UUID	Unique identifier for the token record
`name`	string	Human-readable label you provide at creation
`token_prefix`	string	First 12 characters (e.g. `aat_AbCdEfGh`) for visual identification
`token_hash`	string	SHA-256 hex digest of the raw token — never exposed via API
`is_active`	boolean	`false` immediately after revocation
`expires_at`	datetime (nullable)	UTC expiry; `null` means no expiry
`access_count`	integer	Total number of validated requests
`last_accessed_at`	datetime (nullable)	Timestamp of the most recent validated request

Security Best Practices

One token per client

Issue a separate token for each machine or integration. This lets you revoke access for a specific client without affecting others.

Set expiry dates

Prefer short-lived tokens (30-90 days) over non-expiring ones. Rotate tokens regularly, especially after team member changes.

Store in secrets managers

Never commit tokens to source control. Use environment variables, a password manager, or a secrets manager (Infisical, AWS Secrets Manager, HashiCorp Vault).

Monitor access counts

Unexpected spikes in access_count or activity from an unexpected last_accessed_at timestamp may indicate a compromised token. Revoke immediately if suspicious.

Revoke unused tokens

Periodically audit your token list and revoke any tokens that are no longer in active use or belong to departed team members.

Prefer short names

Use names like cursor-alice-laptop or ci-github-actions so you can identify the token’s origin at a glance when auditing.

A PAT grants access to all MCP instances in its workspace. Treat it with the same care as a root API key. If a token is compromised, revoke it immediately via DELETE /v1/mcp-access-tokens/{id} — revocation takes effect instantly.

Validation Logic

When the MCP proxy receives a request, it validates the Bearer token through the following checks in order:

Format check — token must start with aat_
Hash lookup — SHA-256 of the token is computed and matched against stored hashes
Active check — is_active must be true
Expiry check — expires_at must be null or in the future
Access recording — access_count incremented and last_accessed_at updated

Any failed check returns 401 Unauthorized. The raw token is never logged.

MCP Integration

Learn how AgentArea manages MCP server instances

Security

Workspace scoping, authentication, and secrets management

Get Started

Features

Core Concepts

Technical Deep-Dives

Examples

Deployment

Resources

Community

MCP Access Tokens

MCP Access Tokens

Overview

Workspace-Scoped

Hash-Only Storage

Instant Revocation

Token Format

Lifecycle

API Reference

Using Tokens with MCP Clients

Creating Your First Token

Token Fields Reference

Security Best Practices

One token per client

Set expiry dates

Store in secrets managers

Monitor access counts

Revoke unused tokens

Prefer short names

Validation Logic

MCP Integration

Security

Get Started

Features

Core Concepts

Technical Deep-Dives

Examples

Deployment

Resources

Community

​MCP Access Tokens

​Overview

Workspace-Scoped

Hash-Only Storage

Instant Revocation

​Token Format

​Lifecycle

​API Reference

​Using Tokens with MCP Clients

​Creating Your First Token

​Token Fields Reference

​Security Best Practices

One token per client

Set expiry dates

Store in secrets managers

Monitor access counts

Revoke unused tokens

Prefer short names

​Validation Logic

​Related

MCP Integration

Security

MCP Access Tokens

Overview

Token Format

Lifecycle

API Reference

Using Tokens with MCP Clients

Creating Your First Token

Token Fields Reference

Security Best Practices

Validation Logic

Related