​
401 Authorization header with Bearer token required

Your client reached the MCP endpoint without a Bearer token on a transport request. Fix:
  • send Authorization: Bearer YOUR_API_KEY
  • do not rely on a per-tool _apiKey argument

​
401 invalid API key

The key was present but did not resolve to an active workspace credential. Fix:
  • verify the key value
  • verify the key is still active
  • verify you are using the right environment

​
Your client cannot connect to /mcp

Current clients should use Streamable HTTP at the mounted server URL:
  • https://api.mailkatana.com/mcp
  • transport: Streamable HTTP
Do not append /sse when configuring Codex or another Streamable HTTP client. The /mcp/sse and /mcp/message routes are compatibility endpoints for legacy SSE clients only. If a direct request returns 401, the route exists and your client is still missing or dropping the Authorization header. The header must be forwarded on every MCP HTTP request, not only initialize. If the endpoint returns 404, treat that as a path or deployment problem instead.

​
400 Invalid content type

Streamable HTTP JSON-RPC requests must use Content-Type: application/json. Clients should also advertise Accept: application/json, text/event-stream.

​
A tool you expected is not documented

Public MCP docs list the stable tool surface only. Some registered tools still return placeholder responses and are intentionally omitted until they return real workspace data.

​
Tool returns An unexpected error occurred.

MailKatana sanitizes internal failures before returning them to MCP clients. If you see this message repeatedly:
  • retry the call once
  • verify the target object exists in the workspace
  • confirm your inputs match the documented tool arguments

​
Requests start failing after bursts of traffic

The MCP mount shares the public developer rate limiter.
  • default limit: 600 requests per minute per IP
  • REST and MCP traffic count against the same developer-facing limiter