API tokens

An API token lets the MySpec MCP servers work without a browser sign-in. Use one for anything that runs without a person present: a server, a container, a CI job or a shared machine.

API tokens start with msp_pat_.

Create a token

The organization and access of a token are fixed when you create it. To change either, create a new token.

A token acts as you. It can never do more than your project role allows on each project, and a Read only token acts as Read on every project, even where you are Admin.

Use a token with the remote server

Send the token as a bearer token:

Authorization: Bearer msp_pat_…

See Remote MCP server for client configuration examples.

Use a token with the local server

The simplest option is the MYSPEC_API_TOKEN environment variable in your MCP client’s configuration:

{
  "mcpServers": {
    "myspec": {
      "command": "npx",
      "args": ["-y", "@myspec/mcp-server"],
      "env": { "MYSPEC_API_TOKEN": "msp_pat_…" }
    }
  }
}

On a shared machine, environment variables can be seen by other processes. A credentials file that only you can read is the tighter choice. Save it as ~/.myspec/oauth_creds.json:

{ "apiToken": "msp_pat_…" }

chmod 600 ~/.myspec/oauth_creds.json

The server refuses a credentials file that other users can read.

Which credential wins

The local server uses the first of these that is set, and only that one:

1. The MYSPEC_API_TOKEN environment variable.
2. apiToken in ~/.myspec/oauth_creds.json.
3. The sign-in saved by login.

If the chosen token is rejected, the server stops with an error instead of falling back to another identity.

Check a token

MYSPEC_API_TOKEN=msp_pat_… npx -y @myspec/mcp-server auth status

It prints the organization and whether the token is read-only or read-write, and exits with 0 when the token works.

Extend a token

On the API tokens page, select Refresh next to the token and choose a new expiry. The token value does not change, so anything already using it keeps working without reconfiguration.

A token can be extended up to two years after it was created. After that, create a new one.

Revoke a token

Select Revoke next to the token. It stops working and cannot be re-enabled.

• The remote server can keep accepting it for up to about a minute.
• A local server that is already running can keep using its current sign-in for up to 15 minutes. Restart it to cut access off at once.

The page also shows when each token was last used, which helps you find tokens you no longer need.

Keep tokens safe

• Treat a token like a password. Never commit it to a repository, paste it into a chat or put it in a URL.
• Give each machine or pipeline its own token, so you can revoke one without breaking the others.
• Prefer Read only unless the agent needs to change things.
• Choose the shortest expiry that works for you, and revoke tokens you no longer use.

Troubleshooting