Astrail

Troubleshooting

Fix MCP endpoint, schema, auth, and SDK errors.

Practical runbooks for the errors teams hit after generating a hosted MCP endpoint: 401s, empty tool lists, validation failures, CORS, rate limits, private setup, and SDK build breaks.

Guides

9

Primary path

MCP

Use before

Support

AuthMCP 401

MCP endpoint returns 401 unauthorized

Fix 401 unauthorized responses from a private Astrail MCP endpoint by checking bearer tokens, server visibility, and client config.

First checkConfirm the request sends Authorization: Bearer with an active Astrail API key for the same workspace as the server.
Open runbook
Tool discoverytools/list empty

tools/list returns an empty tool list

Diagnose an empty MCP tools/list response from generated OpenAPI, Code Mode, or private endpoint policy settings.

First checkOpen the server details and confirm the generated endpoint has approved public tools or Code Mode search_docs and execute enabled.
Open runbook
Tool callstools/call validation

tools/call returns a validation error

Fix MCP tools/call validation errors by matching generated schemas, JSON-RPC params, and Code Mode execute arguments.

First checkCall tools/list or search_docs with schema detail and compare the tool arguments against the generated input schema.
Open runbook
GenerationOpenAPI schema issue

OpenAPI schema issues during MCP generation

Resolve OpenAPI parsing, schema validation, missing paths, circular refs, and unsupported content-type issues before generating MCP tools.

First checkOpen the direct OpenAPI JSON or YAML URL and confirm it returns a valid spec with info, paths, operations, and schemas.
Open runbook
AuthMCP auth header

Auth header problems in MCP clients

Fix Authorization header forwarding, bearer token formatting, and client-specific MCP auth configuration problems.

First checkCapture or log the outgoing request and verify the client forwards Authorization: Bearer to the Astrail MCP URL.
Open runbook
NetworkingMCP CORS

CORS and origin issues with hosted MCP

Resolve browser CORS failures, blocked origins, preflight requests, and private network restrictions when calling hosted MCP endpoints.

First checkConfirm whether the request is coming from a browser origin, a backend runtime, or a desktop MCP client because each path has different CORS rules.
Open runbook
ReliabilityMCP 429

MCP rate limit errors and 429 responses

Debug 429 rate limit responses from hosted MCP endpoints, generated tools, and edge abuse protections.

First checkCheck whether the 429 came from Astrail edge limits, workspace billing limits, or the upstream provider API.
Open runbook
Setupprivate MCP endpoint

Private MCP endpoint setup checklist

Set up a private Astrail MCP endpoint with API keys, hidden metadata, allowed tools, credentials, and production verification.

First checkConfirm the server is private, public metadata is filtered, and every client has a scoped Astrail API key.
Open runbook
SDK Factorygenerated SDK build failed

Generated SDK build failures

Fix build, typecheck, package, and smoke-test failures in generated Astrail SDK bundles.

First checkRun the bundle verification script first, then inspect the first compiler error instead of chasing every generated file.
Open runbook