# MCP Troubleshooting
URL: https://docs.autociso.io/developers/mcp/troubleshooting/
Description: Symptom, cause, and fix for the most common AutoCISO MCP connection problems.

Most AutoCISO MCP problems fall into a handful of buckets. Find your symptom below.

## Symptom → cause → fix

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| AutoCISO tools don't appear in the client | Bad JSON, wrong config file path, or the client wasn't restarted | Validate the JSON, confirm the file location, then fully restart the client |
| `404 NOT_FOUND` on `/mcp` | MCP is not enabled for your deployment | Contact support |
| You are not sure the token itself works | — | Make the raw cURL call from the [MCP Quickstart](https://docs.autociso.io/developers/mcp/quickstart/) to rule out client configuration |
| `401` | Token typo, expired, or revoked | Re-copy the token; create a new one in **user menu → API Tokens** if needed (see [API tokens](https://docs.autociso.io/developers/api-tokens/)) |
| `401` right after a `308` | You called `https://autociso.io/mcp`, the legacy URL. It redirects to `https://api.autociso.io/mcp`, and many HTTP clients drop `Authorization` when a redirect crosses hosts | Point the client at `https://api.autociso.io/mcp` directly |
| `403` or any `5xx` | Came from infrastructure, not the MCP app (the app only emits 401/404/429) | Retry; if persistent, contact support |
| No AutoCISO tools, or fewer than expected | The token lacks the scope, or your plan does not include the feature | See [Scope is not entitlement](https://docs.autociso.io/developers/mcp/authentication/#scope-is-not-entitlement) |
| `SCOPE_FORBIDDEN` | Token missing a scope the call needs | Recreate the token with the right scope. See [MCP Auth and Scopes](https://docs.autociso.io/developers/mcp/authentication/) |
| `NOT_PERMITTED` on a write | A write tool was called without its write scope, or with writes disabled for your deployment | Expected, not a bug. See the [Tool Catalog](https://docs.autociso.io/developers/mcp/tools/) |
| `429` | Rate limited | Slow down; the SDKs back off automatically. See [MCP Errors and Retries](https://docs.autociso.io/developers/mcp/errors/#rate-limits) |

## Editor config won't load?

Editor MCP config is JSON and unforgiving:

- Run the file through a JSON validator — a single trailing comma breaks it.
- Confirm the exact file: `.cursor/mcp.json` for Cursor, `.vscode/mcp.json` for VS Code, `claude_desktop_config.json` for Claude Desktop.
- After editing, **reload the window** (editors) or **restart** (Claude Desktop).

See the connect guides for the exact blocks: [Claude Desktop](https://docs.autociso.io/developers/mcp/claude-desktop/) and [Cursor / VS Code](https://docs.autociso.io/developers/mcp/cursor-vscode/). Using an SDK instead? See the [TypeScript](https://docs.autociso.io/developers/mcp/typescript-sdk/) or [Python](https://docs.autociso.io/developers/mcp/python-sdk/) SDK guide.

## Still stuck?

- Map any error code to its cause in [MCP Errors and Retries](https://docs.autociso.io/developers/mcp/errors/).
- If a `404` persists, contact AutoCISO support: MCP is not enabled for your deployment.