# Troubleshooting MCP

> Fixes for common problems connecting Claude Code to APIANT, including missing tools, 401 errors, the MCP Tools permission, outdated skills and locked drafts.

Common MCP problems sit in one of four places: the install in the project directory, Claude Code's sign-in for the `apiant-ai` server, your account's permissions, or a draft another session holds. Find the symptom below. To check the basics first, run `/apiant-setup` in Claude Code from your project directory.

## Install

| Symptom | Cause | Fix |
|---|---|---|
| `claude: command not found` | The Claude Code CLI is not on your `PATH`. | Install or locate Claude Code, then run the install command again. |
| `unzip: command not found` | Mac or Linux without `unzip`. | Install `unzip`, then run the command again. |
| **Connect to Claude Code** is missing from the account menu, or the dialog says "Not available while viewing another account." | You are acting as another account. | Return to your own account and open the dialog again. |
| Skills do not load after install | Claude Code was not restarted, is older than 2.1.157, or was started in another directory. | Start Claude Code in the directory where you ran the command. To restore the skills, run the download half of the command. |

## Connection and sign-in

| Symptom | Cause | Fix |
|---|---|---|
| Claude says it has no APIANT tools | Claude Code was started outside the install directory, the `apiant-ai` server is pending approval, or it needs sign-in. | Run `claude mcp list` in the directory. Approve a pending server by running `claude` there; authenticate one that needs sign-in with `/mcp`. |
| `apiant-ai` shows as needing authentication, or requests to `/mcp` return `401` | No token yet, or the stored token was removed or revoked. | Run `/mcp`, select `apiant-ai`, and authenticate. |
| You have to sign in again after updating | You re-ran the whole install command, whose first step removes the server and its stored sign-in. | Sign in once more. Next time, update with only the download half; see [Connect Claude Code](/docs/mcp/claude-code#update-the-skills). |
| "Your account does not have the MCP Tools permission required to use the plugin" | Your role lacks the **MCP Tools** permission. | Ask your account administrator to add it to your role. |
| Claude Code reports `access_denied`, or the page says "Access denied. You can close this window." | **Deny** was selected on **Authorize access**. | Start the sign-in again from `/mcp` and select **Allow**. |
| Claude works on the wrong APIANT account | Claude acts as whoever signed in on the authorization page. | In `/mcp`, choose **Clear authentication** for `apiant-ai`, then authenticate as the right account. |
| Requests return `401` with `unknown tenant` | The server registration sends an `X-APIANT-Tenant` header value APIANT no longer recognizes. | Copy the command from **Connect to Claude Code** again, run it, and sign in. |

## Notices at the start of a session

| Notice | Meaning | Fix |
|---|---|---|
| "Your APIANT plugin is outdated, re-run the install command from your APIANT account menu.", followed by the path it checked | The skills in this directory differ from the ones APIANT currently serves. | Run only the download half of the install command, then restart Claude Code. This keeps your sign-in. |
| `IMPORTANT: ~~~~~ The APIANT plugin is only compatible with models that have at least a 1M-token context window ~~~~~` | Claude could not confirm that the session's model has a context window of at least 1M tokens. | Switch Claude Code to a model with a context window of at least 1M tokens. |

## Tool errors while working

| Symptom | Cause | Fix |
|---|---|---|
| "this account's plan does not permit app authoring" | Building or editing connectors, triggers and actions is not included in your plan. | Use the catalog's existing operations, or change plans. See [Plans, usage and billing](/docs/account/plans-and-limits). |
| Another permission error on a tool | The tool needs a permission your role lacks, such as creating a connector or deploying to other accounts. | Ask your account administrator. |
| Claude reports that the automation's draft is locked to a different conversation | Another Claude session, or the assistant, has unsaved changes to that automation. | Save or discard the changes in that session. An abandoned lock expires after 30 days. |
| Claude says no diagram comments are pending | Another session already applied them, or Claude is signed in as a different account from the one that queued them. | See [Review a diagram and send comments to Claude](/docs/mcp/diagram-comments#troubleshooting). |
| A tool returns a broken or unexpected result | Possibly a defect on the APIANT server. | Claude reports server defects to APIANT on its own. To add details, ask Claude to report the problem to APIANT. |

## Check the server from a terminal

The server's discovery documents are public. If these commands fail, your machine cannot reach APIANT or APIANT is unavailable; the install is not the cause:

```bash
$ curl -s https://mcp.apiant.ai/.well-known/oauth-protected-resource
{"authorization_servers":["https://app.apiant.ai"],"resource":"https://mcp.apiant.ai"}

$ curl -s -o /dev/null -w "%{http_code}\n" -X POST https://mcp.apiant.ai/mcp
401
```

A `401` from `/mcp` without a token is the expected answer.

## Next steps

- [Connect Claude Code](/docs/mcp/claude-code)
- [Authentication and permissions](/docs/mcp/authentication)
- [Troubleshooting automations](/docs/runs/troubleshooting)