---
title: "Troubleshooting"
description: "Fix common problems with the MySpec MCP servers, organized by the symptom or error message you see."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.myspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

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

> **Local server: start with auth status**
>
> Run `npx -y @myspec/mcp-server auth status`. It shows the account, the
> organization, and which credential the server uses (an API token or your
> `login` session). It exits with `0` when you are signed in and `2` when you
> are not.

## Not signed in

### "Not authenticated" (local server)

```text
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.

1. Run `npx -y @myspec/mcp-server login`, or set up an
   [API token](/mcp/api-tokens/#use-a-token-with-the-local-server).
2. 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:

```bash
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](/guides/teams-and-project-access/) 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](#organization-problems), [Read-only errors](#read-only-errors) and [Permission denied](#permission-denied-for-your-project-role). |
| `404` | Not found in your organization, or you have no access to the project. | See [Projects are missing](#projects-are-missing-or-a-tool-says-not-found). |
| `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"

```text
… 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](/mcp/tools/) 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

```text
… 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](/guides/teams-and-project-access/)
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](/mcp/tools/#project-roles).

## Connector sign-in problems

These apply when you add the [remote server](/mcp/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](/mcp/api-tokens/) 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](/mcp/local-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](/guides/brownfield/) 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](/mcp/tools/#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.

1. Check with `node --version`.
2. Install Node.js 22 or later.
3. 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](/mcp/stream-tokens/#revoke-a-stream-token). |
| 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. |

Source: https://docs.myspec.dev/mcp/troubleshooting/index.mdx