MCP Tokens

MCP tokens authenticate AI assistants connecting to PodWarden. A token carries a stored role, but that role does not restrict the connected AI — see Roles below.

Token format

Tokens use the pwm_ prefix (PodWarden MCP):

pwm_ftf3Vq9azDOOR1S_sWl2AeOrAl3yJUlfDEareE856w4

Tokens are:

• 44 characters long (prefix + 32 bytes URL-safe base64)
• SHA-256 hashed before storage — the plaintext is never stored in the database
• Shown in full only once at creation time (the UI keeps it in memory for your session)

Roles

Do not rely on a role to scope a token. Mint an MCP token only where you would grant full administrative access to the instance, and limit exposure by choosing whether to create the token rather than how to configure it. Revoke it when the assistant no longer needs it.

What does restrict an MCP tool call is the instance-wide read/mutate/destroy tier switch in Settings → MCP, applied identically to every caller, together with a handful of credential-class rules that refuse any MCP token on credential-administration routes. Both are set out in What gates a tool call.

Creating a token

Via the UI

1. Go to Settings → MCP
2. Click Create Token
3. Enter a name (e.g., "Claude Desktop", "Dev testing")
4. Select a role
5. Set expiry (1–365 days, default 90)
6. Click Create

The full token appears in the config snippets above the token table. Copy the config snippet for your client.

Via the API

curl -X POST https://your-podwarden.example/api/v1/settings/mcp-tokens \
  -H "Authorization: Bearer YOUR_ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude Desktop",
    "role": "admin",
    "expiry_days": 90
  }'

The response includes the full token in the token field — this is the only time it's returned.

Managing tokens

Revoking

Revoking a token immediately invalidates it. Any AI assistant using the token will get 401 Unauthorized on the next request.

• UI: Click the trash icon on an active token
• API: DELETE /api/v1/settings/mcp-tokens/{token_id} (on an active token, this revokes it)

Reissuing

Reissuing revokes the old token and creates a new one with the same name and role. Useful when a token may have been leaked.

• UI: Click the rotate icon on an active token
• API: POST /api/v1/settings/mcp-tokens/{token_id}/reissue

Deleting permanently

Revoked tokens can be permanently deleted from the database.

• UI: Click the trash icon on a revoked token
• API: DELETE /api/v1/settings/mcp-tokens/{token_id} (on a revoked token, this deletes it)

Token lifecycle

Created (active) → Revoked → Deleted (permanent)
                 ↘ Expired

• Active: Token works normally
• Expired: Token stops working after the expiry date. Appears in the token list as "Expired"
• Revoked: Token was manually invalidated. Can be permanently deleted
• Deleted: Token record removed from the database

Selecting a token for config snippets

When you have multiple active tokens, the Settings → MCP page shows radio buttons next to each token. Select the token you want in your config snippet — the JSON/command updates automatically.

Tokens and the Hub tunnel

If you use the Hub MCP Proxy, the tunnel creates its own internal token (Hub Tunnel) to execute tool calls locally. This token is managed automatically — you don't need to create or manage it.

Your pwm_ tokens are for direct MCP connections only. Hub proxy connections authenticate at Hub instead — either by signing in with OAuth, or with a personal access token (pwp_) minted from Connect an AI client in Hub Dashboard > MCP access (or on the API Keys page). See Client Configuration for the connection details.

Security considerations

• Tokens are equivalent to API keys — treat them like passwords
• Use the minimum role needed for the task
• Set reasonable expiry periods
• Revoke tokens when no longer needed
• Monitor the Activity Log for unexpected usage
• The MCP Access Level setting (Settings → MCP) further restricts which tools are available, regardless of token role
• Each token is tied to an owner user (the first admin user), but the token's own role controls access
• Hub issues its own credentials, and neither is an MCP token. An instance key (pwh_) connects this PodWarden Core to Hub — it is a machine credential, one per Core. A personal access token (pwp_) is minted by a signed-in human, is scoped to one instance, and is what an AI client presents to Hub's MCP endpoint. MCP tokens (pwm_) authenticate direct connections to your PodWarden instance and are never used against Hub