MCP Troubleshooting
Diagnose missing tools, invalid tokens, permission errors, timeouts, ZIP layout issues, and local HTTP mode.
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