# Troubleshooting

> What each error from your MCP server means, and how to get your client connected again.

This page is about [your MCP server](/docs/mcp/quickstart). For the uare.ai Experts MCP server, see [its errors](/docs/mcp/experts#errors).

## Errors from the server

| Status | Message | What to do |
| --- | --- | --- |
| `401` | `Authorization: Bearer uare_pk_... is required` | Your client isn't sending the key. Check the `Authorization` header in its config. In a terminal, an empty `$UARE_API_KEY` sends `Bearer` with nothing after it and gets this error: `export` the key first. |
| `401` | `Invalid MCP API key format` | The value after `Bearer ` doesn't start with `uare_pk_`. Look for a missing or extra character. If it reads `Bearer undefined`, your code built the header from an environment variable that isn't set where it runs, such as `process.env.UARE_API_KEY`. |
| `401` | `Invalid MCP API key` | The key doesn't exist. Copy it again or [generate a new one](/docs/mcp/api-keys#create-a-key). |
| `403` | `API key has been revoked` | Generate a new key and update your client. |
| `429` | `Too many requests` | You went over the limit of 120 requests a minute. Wait a minute and retry. |
| `503` | `Authentication service unavailable` | A temporary problem on our side. Retry after a few seconds. |

## Check your key from a terminal

Send the first message every MCP client sends:

```bash
curl -s https://app.uare.ai/api/v1/mcp \
  -H "Authorization: Bearer $UARE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
```

A working key answers with an `event: message` line whose data holds the server's `serverInfo`. A refused one answers with one of the errors above.

## Claude Desktop doesn't start the server

Claude Desktop starts `npx` with a minimal `PATH`, so it often can't find Node.js installed through Homebrew, nvm or fnm. Replace `"command": "npx"` with the full path that `which npx` prints in your terminal, then restart Claude Desktop.

Claude Desktop writes MCP logs to `~/Library/Logs/Claude/mcp*.log` on macOS.

On Windows, a key that works elsewhere can fail because Claude Desktop splits the `Authorization` argument at its spaces. Use the config in [Claude Desktop on Windows](/docs/mcp/quickstart#claude-desktop-on-windows).

## The key works in a terminal but not in Cursor

Cursor resolves `${env:UARE_API_KEY}` from the environment it was started in. If you open Cursor from the Dock, it doesn't see variables exported in your shell profile. Start Cursor from a terminal, or put the key directly in `mcp.json` and keep that file private.

## A change through your apps never happens

[`act`](/docs/mcp/tools#act) only stages changes such as sending an email. Your client has to call [`confirm_action`](/docs/mcp/tools#confirm_action) with the token from `pending_actions` within about 10 minutes. If the token expired, ask again.

## `act` can't find your data

`act` only reaches apps you've connected to your AI in uare.ai. Connect the app there first, then try again.