.AIGuideAPIANT.aiv3
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. |
| "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. |
| 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. |
| 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
Related docs
Last updated September 17, 2026