Skip to main content

MCP troubleshooting

Use this shared checklist before debugging a host-specific setup.

Connection​

  • Confirm the endpoint is https://mcp.spectralco.co/mcp.
  • Confirm the host supports the configured MCP transport.
  • Check whether a proxy or firewall blocks HTTP streaming.

Authentication​

  • Confirm OAuth login completed.
  • Confirm scopes include mcp:models:read and any required write scope.

Tools​

  • Confirm the host refreshed its MCP tool list after setup.
  • Confirm write tools require user review or confirmation.
  • Confirm the Spectral account can create a test model in the target workspace.

Expected Endpoint Behavior​

GET /mcp may return 405 Method Not Allowed. That does not mean the server is down. Spectral's MCP endpoint expects protocol requests over HTTP, usually through the MCP host's Streamable HTTP client.

Common Fixes​

  • Restart the MCP host after changing config files.
  • Reconnect OAuth if a tool returns 401 or 403.
  • Confirm the requested scopes include mcp:models:read and mcp:models:write for write workflows.
  • Check host-specific logs: /mcp in Claude Code, MCP logs in Cursor, and codex mcp list or /mcp in Codex.