Skip to content

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

OAuth sign-inPersonal access token
Use it forClaude, Claude Code, Codex, Cursor, VS Code and any client that supports MCP sign-inClients without MCP sign-in, scripts and CI
How you set it upAdd the server URL; the client opens a consent page where you choose AllowCreate a token in Settings, then Access tokens and put it in the client's Authorization header
Secret to storeNone. The client keeps a short-lived access token and refreshes itThe token, which starts with sgp_
Where you revoke itSettings, then Access tokens, then Signed-in agentsSettings, then Access tokens

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:

  1. The client's first request gets 401 Unauthorized with a WWW-Authenticate header that points to https://mcp.specsgraph.io/.well-known/oauth-protected-resource/mcp.
  2. 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.
  3. You sign in to SpecsGraph if you are not already, and the consent page asks what the agent may do.
  4. 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 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.

FieldWhat it sets
OrganisationThe organisation the agent acts in. An agent reaches one organisation; connect again to use another.
ExpiryHow long the sign-in lasts: 30 days, 90 days, 1 year, No expiry. After that, the client asks you to sign in again.
AccessRead only, or Read and write to let the agent stage changes and manage tasks.
ProjectsThe projects the agent can see. It cannot see or change any other project.

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

  1. Open your token settings

    Sign in to the SpecsGraph web app (opens in a new tab) and open 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 and by which client.

  3. 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.

  4. Copy the token, then connect

    Copy the token into the SPECSGRAPH_TOKEN environment 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 with project_list before you leave.

FieldOptionsSuggestion
NameFree textClient plus machine, for example claude-code-laptop.
Expiry30 days, 90 days, 1 year, 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 stage proposals.
ProjectsThe projects you selectOnly the projects the agent works on.

What each access level allows

AccessToolsLimited by
Read onlyAll 16 read tools, such as project_list, spec_get, workstream_listChanges and task_list, plus thread_open, thread_ask, thread_reply so the agent can take part in review.The projects you chose.
Read and writeRead tools plus the 36 write tools, such as spec_apply, task_open and thread_reply.The projects you chose and your role. A Viewer's agent can open, ask and reply in threads but cannot stage a proposal, open a workstream or a task.

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.

~/.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, ~/.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:

  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 (Test connection, or your client's server list).
  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 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