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

# MCP troubleshooting

> What the common errors mean, and where each one is actually coming from.

<AccordionGroup>
  <Accordion title="Authentication required / the client never prompts to sign in">
    The client got a `401` and did not follow it. Discovery lives entirely in the `WWW-Authenticate` header on that response.

    In a browser-based client, the usual cause is CORS: `www-authenticate` has to be an exposed header or the browser cannot read it, and the `401` that should start the OAuth flow becomes a dead end. Confirm your client supports **OAuth 2.1 with dynamic client registration** — MCPulse has no key to paste as a fallback.
  </Accordion>

  <Accordion title="Invalid token — token audience does not include this resource">
    The token was issued for a different resource entirely. Disconnect and re-authenticate so the client obtains a fresh one.

    Both this resource's URL and `authenticated` are accepted audiences — see [MCP authentication](/mcp/auth) for why. A token failing this check was genuinely issued for somewhere else.
  </Accordion>

  <Accordion title="Access is lost roughly every hour">
    No refresh token was issued, so the access token expired and nothing renewed it.

    That happens when `offline_access` is not requested. Reconnect; if it recurs, your client is not requesting the scope, and its OAuth configuration is where to look.
  </Accordion>

  <Accordion title="No MCP named X. Yours are: …">
    Working as intended. The name did not match any MCP on your account, and the error lists the ones that do so the agent can retry correctly.

    Names match case-insensitively after trimming. If yours is in the list and still not matching, check for a trailing space or a non-ASCII character in the name.
  </Accordion>

  <Accordion title="&#x22;staging&#x22; matches 2 MCPs. Use the id instead: …">
    Two MCPs share that name. The server refuses to guess — picking the first would report one server's numbers under the other's name, which is a wrong answer that looks exactly like a right one.

    Use one of the ids from the message, or [rename](/mcps/rename) one of them.
  </Accordion>

  <Accordion title="This account has no MCPs yet">
    You are authenticated against an account with nothing in it. Most often that means signing in with a different address than the one holding your MCPs — an invitation is matched on the exact address.

    See [Invite someone](/team/invite).
  </Accordion>

  <Accordion title="Internal error. The failure has been logged.">
    Something failed on our side. The message is deliberately bare: internal errors carry column names, constraint names and sometimes values, and a tool result goes into a model's context and from there into whatever it says next.

    Retry once; if it persists, report it with the tool name, the arguments and roughly when.
  </Accordion>

  <Accordion title="first_call_rate is null, or retries are zero">
    Not an error. Those come from the [nightly pass](/api/concepts/nightly-pass) at 02:00 UTC and only cover days it has walked.

    `nightly_as_of` in every response says how far it has got. `null` means it has covered none of the range — usually a range that is entirely today, or an MCP on its first day.
  </Accordion>

  <Accordion title="sessions and cost_per_session_usd are null">
    You passed a `tools` filter. Sessions have no tool dimension — a session belongs to the server, not to a tool — so those come back null rather than as unfiltered numbers in a filtered answer.

    Drop the filter to get them. See [The overview](/metrics/overview).
  </Accordion>

  <Accordion title="A write is refused — 'This action requires the admin role'">
    Working as intended. Writes run the same role guards as the REST API, so a **member** can read every number and change nothing. Other sentences from the same family: "Only an owner can do this to another owner", "This is the only owner — promote someone else first", "You cannot do this to yourself".

    See [Roles and permissions](/team/roles). Whoever owns the account can promote you.
  </Accordion>

  <Accordion title="There is no tool to create a key or delete the account">
    Deliberate, and not coming. A minted key would land in the model's context and from there in transcripts and provider logs. A typed-name confirmation for account deletion proves nothing when the model already read the name from `get_account`.

    Both live in the dashboard: [keys](/api-keys/create), [account deletion](/account/delete). See [Tools](/mcp/tools).
  </Accordion>

  <Accordion title="The client confirms every call, even reads">
    Your client is ignoring `readOnlyHint`. The 14 read tools carry it and should not prompt; `delete_mcp`, `revoke_key` and `remove_member` carry `destructiveHint` and should.

    Annotations are hints — a client is free to confirm everything. Check its tool-approval settings.
  </Accordion>
</AccordionGroup>

## Related

* [Connect](/mcp/connect)
* [MCP authentication](/mcp/auth)