# MCP Troubleshooting

> Diagnose missing tools, invalid tokens, permission errors, timeouts, ZIP layout issues, and local HTTP mode.

Canonical: https://staticx.site/documentation/mcp-troubleshooting

Troubleshooting

## Start with the smallest useful check.

StaticX tools return the real API status and message. The MCP server does not fabricate success or silently bypass permissions.

  | Symptom | Check | Fix |
|---|---|---|
| Server does not start | Run `npx -y staticx-mcp-server` manually. | Install Node 18.17 or newer and confirm `npx` is available. |
| No StaticX tools appear | Refresh or restart the client after saving MCP config. | Confirm the config key is `mcpServers`, or `context_servers` in Zed. |
| Token required | Call `staticx_config`. | Set `STATICX_API_TOKEN` in the MCP server environment. |
| HTTP 401 | Call `staticx_auth_check`. | Create a new token if the current token expired or was revoked. |
| HTTP 403 | Check token restriction and permissions. | Use a token scoped to the target site/workspace with the required ability. |
| Site ID required | Pass `project_id` to the tool. | Or set `STATICX_PROJECT_ID` for a one-site agent. |
| Deploy rejected | Inspect the ZIP root. | Ensure `index.html` or `index.htm` and `404.html` exist at the root. |
| Timeout | Inspect network access and API URL. | Set a larger `STATICX_TIMEOUT_MS` only after checking the underlying request. |
| Rollback/delete blocked | Read the tool error. | Provide the exact confirmation text only after reviewing the target. |

  Debug locally

## Start the HTTP transport when your client exposes request details.

 ```
STATICX_API_TOKEN=sx_replace_with_your_token \
STATICX_API_BASE_URL=https://staticx.site/api/v1 \
npx staticx-mcp-server http

# endpoint: http://localhost:3100/mcp
```

[View on staticx.site](https://staticx.site/documentation/mcp-troubleshooting)