Docs / How-To / Token Security

Token Security

Token Security & Rotation

Your MCP token is the key to your workspace. Understand what it is, how to store it safely, and what to do if it's ever compromised.

What Is the MCP Token?

The MCP token is a JWT (JSON Web Token) scoped specifically to a single AgentRQ workspace. When Claude Code connects to AgentRQ via the SSE MCP endpoint, it presents this token in the URL query string — the server validates it and grants access to that workspace's tasks, messages, and tools.

Token Properties

— JWT format — audience claim set to the workspace ID
— Workspace-scoped — grants access to exactly one workspace, no others
— Long-lived — does not expire on a schedule; valid until regenerated
— Encrypted at rest — stored in the database with AES-256-GCM encryption
— Full access — grants read/write access to all tasks and messages in that workspace via MCP

MCP endpoint — token placement

https://WORKSPACE_ID.mcp.agentrq.com/mcp?token=YOUR_MCP_TOKEN
                                                           ↑ token is passed here as a query parameter

Token Security Rules

Shown Once at Creation

The token is displayed exactly once — when you first generate it in the workspace settings. Copy it immediately and store it somewhere safe. The server stores only an encrypted version; it cannot show you the plaintext again.

Never Commit to Git

Do not put a raw token value in .mcp.json and then commit that file. If .mcp.json contains a live token and it ends up in a public (or even private) repo, treat the token as compromised and rotate immediately.

Scope Is Per-Workspace

Each workspace has its own independent token. A leaked token exposes only that workspace — not your account, not other workspaces. This limits blast radius. For sensitive projects, use dedicated workspaces with tightly controlled token access.

Treat It Like a Private API Key

Apply the same practices you use for AWS access keys, Stripe secret keys, or database passwords. Vault it, rotate it on team membership changes, and never share it over insecure channels.

Storing Your Token Safely

The safest approach is to keep the token out of any file that could be committed. Use environment variables and reference them in .mcp.json via Claude Code's env var expansion syntax.

Option 1 — Shell Profile (Recommended)

Add the token to your shell profile as an environment variable. Name it clearly so you know which project and workspace it belongs to.

~/.zshrc or ~/.bashrc

export AGENTRQ_TOKEN_MY_PROJECT="your-token-here"

Option 2 — Reference in .mcp.json via Env Var

Claude Code supports ${ENV_VAR_NAME} expansion in .mcp.json. With this approach, you can safely commit .mcp.json — it contains no secret values.

.mcp.json — safe to commit

{
  "mcpServers": {
    "agentrq": {
      "type": "http",
      "url": "https://WORKSPACE_ID.mcp.agentrq.com/mcp?token=${AGENTRQ_TOKEN_MY_PROJECT}"
    }
  }
}

Option 3 — .env File (Keep Out of Git)

If you prefer a local .env file, make sure it's in your .gitignore. Use a .env.example file (without the actual value) to document the required variable for teammates.

.env (NOT committed)

AGENTRQ_TOKEN_MY_PROJECT=your-token-here

How to Rotate a Token

Token rotation immediately invalidates the old token and generates a new one. Any Claude Code sessions using the old token will lose connectivity until updated.

Go to your workspace settings in the AgentRQ dashboard

Click Regenerate MCP Token

Copy the new token immediately — it won't be shown again

Update your .mcp.json URL (or environment variable) with the new token

Restart Claude Code so it reconnects using the new token — ctrl+c then claude again

Immediate invalidation. The old token stops working the moment you click Regenerate. Any Claude Code session still using the old token will fail to connect. Update your config and restart before resuming work.

When to Rotate

Rotate Immediately If...

You accidentally committed the token to git
You shared it over Slack, email, or an insecure channel
You suspect unauthorized access to the workspace
A device with the token stored was lost or stolen

Rotate as Routine When...

A team member who had the token leaves
You're doing a quarterly security review
You're archiving or handing off a project
You're switching dev machines

MCP Token vs. Session Token

There are two types of tokens in the AgentRQ MCP protocol. You only need to manage one of them.

MCP Token You manage this

Long-lived, workspace-scoped JWT
Set in .mcp.json as ?token=
Manually rotated via dashboard
Requires your attention for security

MCP Session Token Automatic

Short-lived JWT, valid for one session
Created by the server after each initialize
Managed entirely by Claude Code
You never see or handle these

The session token is part of the MCP protocol handshake — Claude Code exchanges the MCP token for a short-lived session token automatically. You only ever need to think about the long-lived MCP token that lives in your .mcp.json or environment variable.

Protect Your .gitignore

Never Commit Tokens to Git

If a token ends up in a git commit — even in a private repository — treat it as compromised. GitHub secret scanning will flag it, but even before that, anyone with repo access can see it in history. Rotate immediately if this happens.

Add these entries to your project's .gitignore to prevent accidental commits of files that might contain tokens:

.gitignore

# Environment and secret files
.env
.env.local
.env.*.local

# Local MCP config overrides (if you keep secrets in a local copy)
.mcp.json.local

# Token files
*.token
*.secret

Safe to Commit

If your .mcp.json uses ${ENV_VAR} syntax for the token (no literal token value), it's safe to commit. This is the recommended approach — teammates clone the repo, set the env var, and connect immediately without any secrets in the codebase.

Workspaces

Create workspaces and manage tokens

Self-Hosting

Run AgentRQ on your own infrastructure

Quick Start

First-time setup and token generation