.AIGuideAPIANT.aiv5
Troubleshooting MCP
Fixes for connecting an AI client to APIANT: missing tools, 401 errors, the MCP Tools permission, leftover skill files and locked drafts.
Common MCP problems sit in one of four places: the server registration in your AI client, the client's sign-in for the apiant-ai server, your account's permissions, or a draft another session holds. Find the symptom below.
Registration
| Symptom | Cause | Fix |
|---|---|---|
claude: command not found | The Claude Code CLI is not on your PATH. | Install or locate Claude Code, then run the command from the dialog again. |
| Connect your AI client 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. |
| The dialog shows no address and says the workspace does not have a web address yet | Your organization's own workspace has no address set. | Ask an administrator to set the workspace's address. Until they do, no AI client can connect to it. |
| Claude says it has no APIANT tools | Claude Code was started in a directory other than the one you registered the server in, 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. |
After the 2026-09-19 change
| Symptom | Cause | Fix |
|---|---|---|
| A tool call is refused with "is not a tool on this connection" | Your client connected before 2026-09-19 and still expects the tool names the retired plugin used. APIANT now exposes three tools, and individual names are not called directly. | Reconnect the server so the client picks up the current tools: restart the client, or toggle the connection off and on. The address itself is unchanged. |
Skill files are still under ./.claude/skills/ | The earlier connect command downloaded them. They are no longer updated; Claude now loads skills over the connection, and their instructions are out of date. | Delete the APIANT skill folders. Leave the rest of .claude/ alone: nothing else in it belongs to APIANT. |
Connection and sign-in
| Symptom | Cause | Fix |
|---|---|---|
apiant-ai shows as needing authentication, or requests to the address return 401 | No token yet, or the stored token was removed or revoked. | Run /mcp, select apiant-ai, and authenticate. |
| "Your account does not have the MCP Tools permission required to use the plugin" | Your role lacks the MCP Tools permission. This is the most common first-connect failure and you cannot fix it yourself. | 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. |
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 is told to load a skill before it can build or edit | The four authoring entry points require the matching skill to have been loaded in that conversation. | None needed. The refusal names the skill and Claude loads it, then retries. |
| 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; your client's registration 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
401
A 401 from the address without a token is the expected answer. If your organization has its own APIANT domain, use the address from the dialog in place of https://mcp.apiant.ai.
Next steps
Related docs
Last updated September 24, 2026