Skip to content

Personal access tokens

Create, scope, store, rotate and revoke the SpecsGraph personal access tokens that MCP agents use to read the system graph and open proposals.

How tokens work

A personal access token lets an MCP client act on your behalf in one workspace. The agent that uses it has your current role, limited further by the token's own scope. Anyone who holds the token can act as you, so treat it like a password.

  • Every token starts with sgp_. The fixed prefix lets you add a secret-scanning pattern that catches a leaked SpecsGraph token; see below.
  • SpecsGraph shows the full token once, when you create it, and cannot show it again. If you lose it, create a new one.
  • Tokens are personal. Each person creates their own, and each client or machine gets its own token so you can revoke one without breaking the others.

Create a token

  1. Open your token settings

    Sign in to your SpecsGraph web app and open Account settings, then Access tokens.

  2. Name it after the client and machine

    Choose Create token and give it a name you will recognize later, such as claude-code-laptop. The name shows in the token list next to when the token was last used.

  3. Set the expiry and scope

    Pick an expiry, an access level and the projects the token can reach. The table below explains each field.

  4. Copy the token

    Copy the token into the SPECSGRAPH_TOKEN environment variable before you close the dialog. You will not see it again.

FieldOptionsSuggestion
NameFree textClient plus machine, for example claude-code-laptop.
Expiry30 days, 90 days, 1 year or no expiry90 days for everyday use. Shorter for a one-off experiment.
AccessRead only, or Read and writeRead only for agents that only need context. Read and write for agents that should draft proposals.
ProjectsThe projects you selectOnly the projects the agent works on.

What each access level allows

AccessToolsLimited by
Read onlyAll 11 read tools, such as get_context and search_graph.The projects on the token.
Read and writeRead tools plus the write tools, such as propose_requirement and comment_on_proposal.The projects on the token and your role. A Viewer's agent can reply in threads but cannot open proposals.

Workspace Admins set the token policy for the workspace, such as the longest expiry members may choose and whether Read and write tokens are allowed. If an option is missing from the dialog, the policy has turned it off.

Store the token safely

Keep the token in an environment variable, and have client configuration refer to the variable instead of the value. These docs use SPECSGRAPH_TOKEN throughout. Set it in your shell profile, or load it from your password manager or secret store when the shell starts.

~/.zshrc or ~/.bashrcShell
export SPECSGRAPH_TOKEN="sgp_paste-your-token-here"

Warning

Never commit a token

Configuration files such as .mcp.json, .cursor/mcp.json and .vscode/mcp.json are often committed. Put a variable reference in them, never the token itself, and keep any .env file in .gitignore. Each client guide shows the variable syntax that client understands.

To catch mistakes before they spread, add a custom pattern to your secret scanner that matches tokens starting with sgp_. A commit that contains one then fails the check instead of reaching your remote.

Rotate a token

Rotate tokens before they expire, and any time you suspect one has been exposed. Rotation never needs downtime:

  1. Create a new token with the same scope.
  2. Update SPECSGRAPH_TOKEN (or your client's stored secret) with the new value.
  3. Restart the client or reconnect the server, and check that the tools still load.
  4. Revoke the old token with Revoke in the token list.

Revoke a token

Revoking a token takes effect right away. The next request from any client using it gets 401 Unauthorized. Proposals, comments and decisions the agent already created stay in place, attributed to you through that agent, so reviewers can still follow the history.

Review your token list from time to time. A token that has not been used in months is a token you can revoke.

When a member leaves or changes role

  • Removed from the workspace. Every token that person created for the workspace stops working immediately. Their past proposals and review comments keep their name.
  • Role changed. Tokens follow the new role on the next request. If an Editor becomes a Viewer, their agent can no longer open proposals, even with a Read and write token.
  • Lost laptop. Revoke the tokens named after that machine.

Next steps