Troubleshooting

Fix common problems with the MySpec MCP servers, organized by the symptom or error message you see.

Find the message or symptom you see. Most problems come from the sign-in, the organization, or the access a token or connection has.

Not signed in

“Not authenticated” (local server)

Not authenticated. Set MYSPEC_API_TOKEN to a MySpec API token, or run
`npx @myspec/mcp-server login` to sign in.

The server has no working credential. You may never have signed in, or your sign-in ended and could not be renewed.

Run npx -y @myspec/mcp-server login, or set up an API token.
If tools still fail after you sign in, restart the server from your client (reconnect it, or restart the client).

If you set MYSPEC_API_TOKEN and the server still says you are not signed in, your package is older than 0.3.0. npx -y @myspec/mcp-server always fetches the latest version.

“Refusing to load credentials … file mode is too permissive”

Other users on the machine can read ~/.myspec/oauth_creds.json, so the server refuses to use it. Run the chmod 600 command from the message, then try again.

Organization problems

Every sign-in and every API token works in one organization. A project in another organization looks as if it does not exist.

Signed in, but every call is refused

The local server shows one of these:

Your CLI session has no active organization (for example when you start reverse).
Tools fail with missing required claims (sub, org).
auth status shows Organization: none.

Your sign-in has no organization selected. This happens when you belong to more than one organization and none was chosen. Sign in again and choose one:

npx -y @myspec/mcp-server login --org <slug>

Projects are missing, or a tool says “not found”

You are working in a different organization from the one that holds the project, you have no access to the project, or the project or file was deleted.

Local server: check the organization with auth status. Switch with login --org <slug>.
API token: a token only works for the organization you chose when you created it, and that cannot be changed. Create a token for the right organization.
Connector (Claude, ChatGPT): you chose the organization when you connected. Disconnect the app under Connected apps and connect it again.
No access to the project: a project you have no project role on is left out of list_projects, and other tools say it is not found. Ask someone with Admin on the project, or an organization owner or admin, to give you access.

“You are not a member of an organization with slug …”

The slug you passed to --org does not match any of your organizations. The message lists the ones you belong to. Use one of those.

In a shell where the CLI cannot ask you (for example a script or CI), login cannot choose for you when you belong to several organizations. Pass --org.

HTTP status codes

Status	Meaning	What to do
`401`	The credential is missing, malformed, unknown, revoked or expired. For a connector, the app may have been disconnected, or you left the organization.	Remote server: check the `Authorization: Bearer msp_pat_…` header, create a new token, or reconnect the app. Local server: run `login` again, or create a new token.
`401` that says the token owner no longer has access to its organization	You left the token’s organization or were removed from it.	Create a token for an organization you belong to.
`403`	You are not allowed to do this: the target is in another organization, your role does not allow it, or the token or connection is read only.	See Organization problems, Read-only errors and Permission denied.
`404`	Not found in your organization, or you have no access to the project.	See Projects are missing.
`429`	You are rate limited.	Wait a little, then try again.
`502` or an error that says it is not a problem with your token	A temporary problem on MySpec’s side.	Retry shortly.

Read-only errors

“This API token is read-only”

… failed: this API token is read-only; mutating tools require a read-write token.

A Read only API token can see every tool, but tools that change data are refused. A token’s access is fixed when you create it, so create a new token with Read and write access. The tool reference marks which tools change data.

“The tool … changes data; reconnect MySpec with write access”

You connected an app such as Claude or ChatGPT without ticking Also make changes.

Claude and Claude Code ask you to reconnect with write access by themselves. Approve it on the MySpec consent page.
ChatGPT does not ask. Open the avatar menu in MySpec, choose Connected apps and Disconnect the app. Then connect again from ChatGPT and keep Also make changes ticked.

Permission denied for your project role

… failed: permission denied — this action needs the write role on the project; you have read. Ask a project admin for access.

You can see the project, but your project role is too low for this tool. For example, read can’t change spec files or start sessions, and only admin can rename, archive or delete the project. The message names the role the tool needs and the role you have. get_project shows your role as viewer_role.

A new token or connection will not help. Ask someone with Admin on the project, or an organization owner or admin, to raise your role. See Project roles.

These apply when you add the remote server as a connector in Claude, ChatGPT or another app.

Problem	What to do
The app never opens a sign-in page, or says it cannot reach the server	Check that the URL is exactly `https://mcp.myspec.dev/mcp`, including `/mcp`.
Every call fails with `401` right after you signed in	The URL in the app must be exactly `https://mcp.myspec.dev/mcp`. Fix it and connect again.
“The app asking for access is not recognised”	Start again from the app. If it keeps happening, the app may not support MCP sign-in. Use an API token instead.
“The app asked to be sent back to an address it did not register” or “The app asked for access MySpec does not offer”	The app’s sign-in request is not one MySpec accepts. Start again from the app. If it keeps happening, use an API token.
The app reports that a `resource` is required after you sign in	The app does not fully support MCP sign-in. Use an API token.
“This request expired”	Reload the consent page, or start again from the app.
“Too many attempts”	Wait a minute, then try again.
“You need to belong to an organization before you can connect an app”	Select Set up an organization, then connect again.
A disconnected app or revoked token still works for a moment	Expected. Access ends within about a minute. A local server that is already running can keep its sign-in for up to 15 minutes; restart it to cut access at once.

`login --paste` errors

--paste signs you in when the browser runs on another machine. If the sign-in page cannot reach the CLI, it shows Finish CLI sign-in with a value like <code>.<state>.

Message	What to do
`Pasted token is missing a state suffix`	You pasted only part of the value, for example the `code` from the address bar. Select Copy code on the page, which copies the whole value including the dot, and paste that.
`Pasted token state does not match this CLI session`	The value comes from a different sign-in attempt. Paste the value from the link this `login` printed, or run `login --paste` again.
`OAuth code exchange failed: HTTP 401`	The value expired. It lasts about a minute after you finish signing in. Run `login --paste` again and paste the value as soon as it appears.
`Timed out waiting for OAuth callback`	The CLI waited too long for the sign-in to finish. Run `login` again.

Only open the sign-in link on a machine you trust. See Local MCP server.

Brownfield session cannot read your code

Brownfield sessions read your code through the local server’s reverse bridge. This applies even when your coding agent uses the remote server: the remote server cannot reach your files.

Symptom	What to do
`start_spec_session` returns a warning that no bridge is connected	Start `npx -y @myspec/mcp-server reverse --root <path>` and leave it running. The session itself was created.
The AI says it cannot read your files	Check that `reverse` is still running, that it runs with the same MySpec account you use in the browser, and that `--root` points at the project folder.
`reverse` stopped after you started another one	Only one bridge runs per account. The newer one takes over and the older one stops.
`reverse` says `cannot obtain access token`	Run `npx -y @myspec/mcp-server login`, or set up an API token, then start it again.
`reverse` says `token rejected after refresh attempt`	Run `login` again. If you belong to several organizations, use `login --org <slug>`.
`reverse` keeps printing `reconnecting in …`	It lost its connection and retries by itself. Check your network.

See Work on an existing codebase for the full setup.

`update_spec_file` conflicts

Message	What to do
`… was NOT updated: … changed it … since you read it`	Someone else saved the file after you read it, and their version was kept. Read the file again, combine your change with theirs, and update with the new `content_version` as `expected_version`. Do not resend the same content: that would undo their work.
`… was NOT updated: this project requires every update to declare the version it was based on`	Read the file first and pass its `content_version` as `expected_version`.
`expected_version is required`	The remote server always needs it. Read the file with `read_spec_file` or `get_spec_file` first.

Comment edits work the same way, but update_spec_file_comment needs the comment’s own content_version. Read it again with list_spec_file_comments. Starting a thread or replying fails with a conflict when the file is in the Trash Bin; restore the file first.

See Edit safely with content_version.

`start_spec_session` takes a long time

start_spec_session waits for MySpec’s first reply, for up to 75 seconds.

pending_action is turn_still_running. This is not an error. The session exists and its first reply finishes in the background. Open session_url to see it. Do not call the tool again.
Your client gave up before the tool returned. The session may already exist. Check list_spec_sessions before you try again, or you may create a duplicate session that also uses AI.
The result has first_turn_error. The session was created, but its first message was not sent. Open session_url and send it from there.
The tool refused to start. Nothing was created. Check the message: the workflow_id may be unknown or not match mode, an attachment or spec file id may not belong to the project, or the token may be read only.

Node.js version too old

The local server needs Node.js 22 or later. With an older version, npm warns about an unsupported engine and the server can fail to start.

Check with node --version.
Install Node.js 22 or later.
Restart your MCP client.

Desktop apps can use a different Node.js than your terminal. If your terminal shows version 22 or later but the client still fails, set the client’s command to the full path of npx from your newer Node.js.

Other errors

Problem	What to do
`read_spec_file` refuses a file	It reads text files up to 8 MiB. On the local server, use `download_spec_file`, which handles binary files and files up to 50 MiB. On the remote server, open the file in the web app.
`read_attachment` refuses a PDF, DOCX or XLSX file	These cannot be read through MCP. Open them in the web app.
`delete_project` or `delete_spec_session` refuses	Only archived projects and sessions can be deleted. Archive it first, if that is really what you want. `delete_project` also needs the `admin` role on the project, and `delete_spec_session` needs `write`.
Revoking a stream token fails with `403`	Revoking a token someone else created needs the Owner or Admin role. See Stream tokens.
The remote server offers no tools, or a tool is “not found”	The `X-MCP-Tools` header names no known tool, or misspells one. Names are case-sensitive. Fix or remove the header.