Sign-in and access tokens
How MCP agents authenticate to SpecsGraph: OAuth sign-in with a consent page, or personal access tokens. Create, scope, rotate and revoke either one.
Two ways to authenticate
Either way, the agent acts as you in one organisation, with your current role, narrowed further by the access level and projects you chose. Anything it writes is recorded as an agent acting for you, with an Agent badge that names the client.
Sign in with OAuth
The SpecsGraph MCP server follows the MCP authorization specification. A client that supports it needs only the server URL:
- The client's first request gets
401 Unauthorizedwith aWWW-Authenticateheader that points tohttps://mcp.specsgraph.io/.well-known/oauth-protected-resource/mcp. - That document names the authorization server,
https://app.specsgraph.io. The client registers itself there, then opens the sign-in page in your browser. It uses PKCE, so no client secret is involved. - You sign in to SpecsGraph if you are not already, and the consent page asks what the agent may do.
- When you allow it, the browser returns to the client with a code, and the client exchanges it for its own grant: an access token and a refresh token.
The consent page
The page is headed "Allow <client> to use SpecsGraph?". The client names itself, and SpecsGraph cannot check that name, so it is always shown with Name not verified and the address the browser will return to, such as claude.ai or localhost for a client on your computer. If the return address is not the client you started from, choose Deny.
Access tokens from sign-in last one hour; the client refreshes them on its own until the expiry you chose or until you revoke the agent. A signed-in agent has the same limits as a token.
Revoke a signed-in agent
Open Settings, then Access tokens, then Signed-in agents. The list shows each client next to your tokens, with its scope, last use, expiry and status. Choose Revoke next to the client, then Revoke agent. Its access ends at once; to use it again, connect from the client and allow it again. Removing the connector in the client alone does not revoke it in SpecsGraph.
How tokens work
A personal access token lets an MCP client act on your behalf in one organisation. The agent that uses it has your current role, limited further by the token's own access and projects. 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. - 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
Open your token settings
Sign in to the SpecsGraph web app (opens in a new tab) and open Settings, then Access tokens.
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 and by which client.Set the expiry, access and projects
Pick an expiry, an access level and the projects the token can reach. The table below explains each field.
Copy the token, then connect
Copy the token into the
SPECSGRAPH_TOKENenvironment variable before you close the dialog. The dialog shows the Connect an agent panel: pick your client's tab, copy the snippet, and press Test connection to see that the server lists 52 tools, starting withproject_listbefore you leave.
What each access level allows
Organisation Admins set the token policy, such as the longest expiry members may choose and whether Read and write access is allowed. If an option is missing from the dialog, the policy has turned it off. The same limits apply on the consent page.
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.
export SPECSGRAPH_TOKEN="sgp_paste-your-token-here"Warning
Never commit a token
Configuration files such as .mcp.json, .cursor/mcp.json, ~/.codex/config.toml and .vscode/mcp.json are often committed or shared. 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. OAuth sign-in avoids the problem entirely.
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. A client that sends the variable name unexpanded gets a 401 whose message says so.
Rotate a token
Rotate tokens before they expire, and any time you suspect one has been exposed. Rotation never needs downtime:
- Create a new token with the same scope.
- Update
SPECSGRAPH_TOKEN(or your client's stored secret) with the new value. - Restart the client or reconnect the server, and check that the tools still load (Test connection, or your client's server list).
- 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 with "This access token was revoked." Revisions, comments and task events the agent already created stay in place, attributed to you through that agent (the Agent badge keeps the client's name), 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 organisation. Every sign-in and token that person has for the organisation stops working immediately. Their past revisions and comments keep their name.
- Role changed. Sign-ins and tokens follow the new role on the next request. If an Editor becomes a Viewer, their agent can no longer stage proposals, even with Read and write access.
- Lost laptop. Revoke the tokens named after that machine, and any signed-in agents on it in Signed-in agents.
Next steps
- Connect an agent: how the token is used on each request.
- Claude Code: add the server and sign in.
- Members and roles: what each organisation role can do.