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

# Troubleshooting

> Fixes for a NeetoInvoice MCP server that will not connect or respond.

The checks differ by how you connected, so start with the section that matches your client.
See the matrix on [Connect](/mcp/connect#which-method-does-my-client-use).

## OAuth connections (Claude, ChatGPT)

<AccordionGroup>
  <Accordion title="The browser window never opens, or approval does not stick">
    **Cause**: the connector was added but never authorized.

    **Fix**: open the connector and click **Connect**. Adding the URL only registers the
    server; the grant is a separate step.
  </Accordion>

  <Accordion title="The assistant sees the wrong workspace">
    **Cause**: the grant covers the workspace you picked during approval.

    **Fix**: ask the assistant to run `ListWorkspaces` to see what the connection reaches. To
    use a different workspace, add it as a separate connection and approve that one.
  </Accordion>

  <Accordion title="Records you expect are missing">
    **Cause**: this is OAuth working as intended. The assistant acts as you, so it sees only
    what your role permits: other people's time entries, payroll, and PTO reports are all
    gated separately.

    **Fix**: ask an admin to adjust your role, or use an API key if you genuinely need
    workspace-wide access. See [Authentication](/mcp/authentication).
  </Accordion>

  <Accordion title="Access stopped working after a while">
    **Cause**: the grant was revoked, or the refresh token was invalidated.

    **Fix**: remove the connector and add it again to re-approve.
  </Accordion>
</AccordionGroup>

## API key connections (Claude Code, Codex, Cursor, Gemini CLI, VS Code, Windsurf)

<AccordionGroup>
  <Accordion title="The server never appears">
    **Cause**: usually the config was not re-read, or a key name is wrong for that client.

    **Fix**: restart the client after saving; in Cursor a window reload is enough, and Windsurf
    also needs the server enabled under **Settings → Cascade → MCP Servers**. Then check the
    three keys that differ per client: VS Code nests under `servers` while others use
    `mcpServers`; Windsurf uses `serverUrl` and Gemini CLI uses `httpUrl` while others use
    `url`; Codex uses TOML, not JSON. A config with the wrong shape parses fine and is
    silently ignored.
  </Accordion>

  <Accordion title="The config file is in the wrong place">
    **Cause**: paths differ per client.

    **Fix**: they are listed on [Connect](/mcp/connect): `~/.claude.json`,
    `~/.codex/config.toml`, `~/.cursor/mcp.json`, `~/.gemini/settings.json`, `.vscode/mcp.json`
    (inside the workspace, not your home directory), and
    `~/.codeium/windsurf/mcp_config.json`.
  </Accordion>

  <Accordion title="Every call fails with an auth error">
    **Cause**: the header value must read `Bearer YOUR_API_KEY` with a single space, where
    `YOUR_API_KEY` is replaced by the real key. Pasting the key without the `Bearer ` prefix
    is the common slip.

    **Fix**: correct the value and restart the client so it re-reads the config. On Codex,
    check that the environment variable named in `bearer_token_env_var` is actually exported
    in the shell that launches Codex.
  </Accordion>

  <Accordion title="The key belongs to a different workspace">
    **Cause**: a key generated in one workspace does not work in another.

    **Fix**: generate a key inside the workspace you want to reach. See
    [Authentication](/mcp/authentication).
  </Accordion>

  <Accordion title="VS Code is too old, or Copilot is not in Agent mode">
    **Cause**: MCP servers need VS Code 1.99 or later, and the tools only appear when Copilot
    Chat is in Agent mode.

    **Fix**: check the version under **Code → About**, and switch the Copilot Chat mode
    selector to Agent.
  </Accordion>
</AccordionGroup>

## Any connection

<AccordionGroup>
  <Accordion title="The endpoint URL is not exact">
    **Cause**: it is `https://connect.neetoinvoice.com/mcp/messages`. Your workspace subdomain
    does not appear in it: the credential identifies the workspace, so a URL built from your
    subdomain will not resolve.
  </Accordion>

  <Accordion title="Windsurf has hit its tool limit">
    **Cause**: Windsurf caps how many MCP tools it loads across all servers. With several
    enabled, some NeetoInvoice tools are dropped.

    **Fix**: disable servers you are not using under **Settings → Cascade → MCP Servers**.
  </Accordion>

  <Accordion title="The request is too vague to route">
    **Cause**: the assistant could not map the request to a tool.

    **Fix**: name the resource. "Show unbilled time entries on Website Redesign for July"
    routes cleanly; "show me the hours" often does not. See [Examples](/mcp/examples).
  </Accordion>

  <Accordion title="The tool does not exist">
    **Cause**: the server exposes a fixed set of tools, listed on [Tools](/mcp/tools).

    **Fix**: anything outside that set, such as editing an invoice after it is generated, has
    to go through the [REST API](/getting-started/introduction) or the app.
  </Accordion>
</AccordionGroup>

## Still stuck?

Visit the [help center](https://help.neetoinvoice.com), email
[support@neetoinvoice.com](mailto:support@neetoinvoice.com), or join the
[Neeto Community](https://neeto.com/community).