# 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](/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 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](/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; 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

- [Connect your AI client](/docs/mcp/claude-code)
- [Authentication and permissions](/docs/mcp/authentication)
- [Troubleshooting automations](/docs/runs/troubleshooting)