---
title: "Token Security & Rotation | AgentRQ Docs"
url: https://agentrq.com/docs/howto-token-rotation
description: "Secure your AgentRQ MCP tokens. Learn how to store them safely, rotate them when needed, and avoid common security mistakes."
---

[Docs](https://agentrq.com/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
- — Stateless authentication — cryptographically signed JWT validated on each request (no DB lookup or token key storage needed)
- — 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

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.

1

Go to your workspace settings in the AgentRQ dashboard

2

Click Regenerate MCP Token

3

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

4

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

5

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.

## Related Pages

[Workspaces Create workspaces and manage tokens](https://agentrq.com/docs/workspaces) [Self-Hosting Run AgentRQ on your own infrastructure](https://agentrq.com/docs/howto-self-hosting) [Quick Start First-time setup and token generation](https://agentrq.com/docs/getting-started)