MCP Tokens

MCP tokens authenticate AI assistants connecting to PodWarden. Each token has a role that controls what the connected AI can do.

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

Each token is assigned a role that maps to PodWarden's RBAC system.

Recommendation: Use operator for day-to-day AI assistant use. Reserve admin for tokens that need to manage secrets or system configuration. Use viewer for monitoring-only connections.

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": "operator",
    "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 use pwc_ API keys from Hub Dashboard.

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 API keys (pwc_) are different from MCP tokens (pwm_). Hub API keys authenticate to Hub's MCP proxy; MCP tokens authenticate direct connections to your PodWarden instance