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

# Troubleshooting

> Fix a NeetoDesk MCP connection that will not connect, will not authenticate or cannot see your data.

The checks differ by how you connected, so start with the section that matches your client.

## Any connection

<AccordionGroup>
  <Accordion title="The assistant does not offer any NeetoDesk tools">
    The server is configured but not connected. Most clients need a restart, or a window reload,
    after the config file changes. Check the client's own MCP panel for the connection's status
    rather than assuming it came up: Claude Code has `/mcp`, Cursor lists servers in settings,
    and Windsurf shows them under **Settings** → **Cascade** → **MCP Servers**.
  </Accordion>

  <Accordion title="Confirm the server is reachable">
    The endpoint answers unauthenticated requests with a 401, which is the expected response and
    confirms it is up:

    ```bash theme={"system"}
    curl -i -X POST https://connect.neetodesk.com/mcp/messages \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
    ```

    A `401` with a `WWW-Authenticate` header is a healthy server. Anything else, or no response,
    points at your network rather than at your setup.
  </Accordion>

  <Accordion title="The assistant reports a tool it cannot find">
    Some tools do not exist. Read [Tools](/mcp/tools) for the full set. There is no tool for
    deleting a ticket, for reading or updating a customer, or for editing a comment after it is
    posted.
  </Accordion>
</AccordionGroup>

## OAuth connections

<AccordionGroup>
  <Accordion title="The browser never opens, or the sign-in page does not load">
    Add the server without a credential. Supplying an `Authorization` header makes the client
    treat the connection as already authenticated, so it never starts the OAuth flow. Remove the
    header, then reconnect.
  </Accordion>

  <Accordion title="The connection worked and has now stopped">
    The grant was revoked, or the refresh token expired. Sign in again from the client: in
    Claude Code that is `/mcp`, in Codex `codex mcp login neetodesk`. Other clients prompt on
    the next request.
  </Accordion>

  <Accordion title="Connected to the wrong workspace">
    The workspace is fixed when you approve the grant, so it cannot be switched afterwards.
    Remove the connection, add it again, and pick the right workspace at the prompt.
  </Accordion>

  <Accordion title="Gemini CLI will not connect">
    Check the key is `httpUrl` and not `url` in `~/.gemini/settings.json`. `url` selects SSE,
    which this server does not serve. See [Connect](/mcp/connect).
  </Accordion>
</AccordionGroup>

## API key connections

<AccordionGroup>
  <Accordion title="Every request is rejected as unauthorized">
    Work through these in order:

    * The key goes in an `Authorization: Bearer <key>` header. The `X-Api-Key` header is for the
      [REST API](/getting-started/authentication) and is not read here.
    * Confirm the key is still active in your workspace admin panel. A deleted key fails the
      same way a mistyped one does.
    * Confirm the key belongs to the workspace in the URL. Keys are per workspace, so a key from
      one subdomain will not work against another.
  </Accordion>

  <Accordion title="Check the config key your client expects">
    They differ, and a wrong key is silently ignored rather than reported:

    | Client                                    | Top-level key          | URL field                                                           |
    | ----------------------------------------- | ---------------------- | ------------------------------------------------------------------- |
    | Claude Code, Cursor, Gemini CLI, Windsurf | `mcpServers`           | `url`, except `httpUrl` for Gemini CLI and `serverUrl` for Windsurf |
    | VS Code                                   | `servers`              | `url`                                                               |
    | Codex                                     | `[mcp_servers.<name>]` | `url`                                                               |

    Codex's config is TOML, not JSON. Its `bearer_token_env_var` takes the *name* of an
    environment variable rather than the key itself.
  </Accordion>

  <Accordion title="Windsurf reports too many tools">
    Windsurf caps you at 100 tools across every connected server. Turn some other servers off
    under **Settings** → **Cascade** → **MCP Servers**.
  </Accordion>
</AccordionGroup>

## Missing or unexpected data

<AccordionGroup>
  <Accordion title="A ticket you can see in the web app is missing from the results">
    On an OAuth connection this is usually correct behaviour, not a fault. The connection is
    scoped to the person who approved it, so an agent restricted to their own tickets or to
    their groups gets a narrowed list. Confirm which account approved the grant, and check that
    account's role. See [Authentication](/mcp/authentication).
  </Accordion>

  <Accordion title="The assistant sees more than the person using it should">
    That is the API key behaving as designed. A key carries no identity, so the connection
    reaches the whole workspace. Switch the connection to OAuth if you want it bounded by a
    person's role.
  </Accordion>

  <Accordion title="A form is missing from the list">
    Only enabled forms are returned. Check the form is enabled in your workspace settings.
  </Accordion>

  <Accordion title="A draft written by the assistant was not emailed to the customer">
    Drafts are saved on the ticket, unsent, for you to review and send from NeetoDesk. Comments
    written through this server are stored on the ticket and are never emailed to the customer
    either.
  </Accordion>
</AccordionGroup>