Networking
CORS and origin issues with hosted MCP
Resolve browser CORS failures, blocked origins, preflight requests, and private network restrictions when calling hosted MCP endpoints.
Symptom
A browser-based app cannot call the MCP endpoint, but server-side curl or a backend worker can.
First check
Confirm whether the request is coming from a browser origin, a backend runtime, or a desktop MCP client because each path has different CORS rules.
Quick fix
Proxy browser calls through your backend or configure an allowed origin for the exact production domain before exposing the endpoint to users.
Separate browser CORS from endpoint reachability
A CORS error means the browser blocked access to the response. It does not prove the MCP endpoint is down. Test the same initialize request from a server-side runtime to confirm network reachability.
Use backend calls for private endpoints
Private MCP endpoints usually need bearer tokens. Browser apps should avoid holding those tokens directly. Put the key in a backend route, call Astrail server-side, and return only the safe result to the browser.
Match exact origins
Origins include scheme, host, and port. https://app.example.com and https://www.example.com are different origins. Preview domains, localhost ports, and staging domains need their own policy during testing.
Handle preflight requests
Authorization and JSON content types can trigger OPTIONS preflight requests. If the preflight is blocked by a proxy or WAF before it reaches the MCP route, the browser will fail before the JSON-RPC body is sent.
FAQ
Does a desktop MCP client need CORS?
Usually no. CORS is a browser enforcement model. Desktop and server runtimes still need network access and valid auth.
Should I allow every origin?
No. Use exact production and staging origins, especially when the endpoint can trigger billable or state-changing tool calls.