Skip to content
Docs

Search the docs

Find a page or a section

MCP

Troubleshooting

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

View as Markdown

This page is about your MCP server. For the uare.ai Experts MCP server, see its 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.
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.

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 only stages changes such as sending an email. Your client has to call 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.