# MCP troubleshooting

> Use this page to find the cause of a failed MCP call and the fix for it.

## Common symptoms

| Symptom | Cause | Fix |
|---|---|---|
| 401 unauthorized | The Authorization header is missing, or the key is wrong. | Send `Authorization: Bearer <key>` in the server entry of your client (the `--header` option for Claude Code, `headers` in Cursor's `mcp.json`), with a key that starts `fsa_` (an app key) or `fsk_` (a person's key). Check that the variable holds the full key. |
| Only provision_app is listed | No Authorization header was sent. | Add the header to the server entry. Without it, Harny lists only provision_app. |
| A tool is refused for this key | The key type does not match the tool. For example, an app key (`fsa_`) cannot call assemble_context. | Use a person's key (`fsk_`) for ingest_text, assemble_context, list_tools, configure_oauth and action_history. Use the app key (`fsa_`) for provision_user, get_claim_link and get_setup_bundle. |
| Empty recall | Nothing has been written for that person yet, or you called with a different person's key. | Check that you call with the key of the person whose memory you expect. Write a note with ingest_text, then call assemble_context again. |
| 429 | The per-minute limit was reached. | Wait for the number of seconds in Retry-After, then retry. |
| The assistant cannot see the tools | The client loaded the server before it was added. | Restart the client after you add the server. |

If a symptom does not match a row, call `diagnose` with your key. It reports the state of each part of the connection and how fresh each connected source is.

## Check the connection

1. Confirm the server address is `https://api.harny.ai/v1/mcp/mcp`.
2. Confirm the Authorization header is present and holds the right key.
3. Restart the client.
4. Call `describe`. It lists the tools this key may call.

## Key types

- A person's key starts with `fsk_`. It names its own user. Calls are scoped to that user.
- The app key starts with `fsa_`. Keep it in your secret store. Do not put it in a browser.
- The server accepts bearer keys and sign-in tokens. A sign-in token that has expired or was disconnected by the owner is refused; sign in again.

## Limits

Calls follow the same limits and refusals as the REST routes they wrap. For the Memory API, see the [Memory API errors](/docs/memory-api/errors) page.

## Next

- [MCP limits](/docs/mcp/limits)
- [MCP keys and access](/docs/mcp/keys-and-access)
- [Memory API errors](/docs/memory-api/errors)