Skip to content

Troubleshooting

Authentication

McpAuthorizationError and the browser never opens

Your client URL is missing the /mcp sub-path. Use the full URL:

https://mcp.io-aerospace.org/mcp

The bare origin (https://mcp.io-aerospace.org) is ambiguous about the trailing slash and breaks the OAuth resource-indicator flow.

401 Unauthorized after a successful sign-in

The token is valid but its aud does not match the server's expected audience. This usually means the client did not send the correct resource parameter in the token request. Clear cached tokens, re-run discovery, and let the client refetch.

Tokens stop working after a while

Access tokens expire (typically in minutes to hours). Your client should be using offline_access to refresh them transparently. If yours does not, you will need to sign in again periodically.

403 Forbidden after a successful sign-in

Authentication passed, but the license check rejected you. Your WorkOS email has no active license on the IO Aerospace license server, or it has expired. Contact IO Aerospace to renew or request access.

Tool calls

A tool returns NaN or Infinity

That's a real result. Astrodynamics quantities legitimately take those values for parabolic / hyperbolic / degenerate inputs (e.g. ComputeOrbitalPeriod on an unbound orbit, range rate at zero range). The server emits them as the IEEE named literals and a compliant JSON parser will keep them. Don't reject the response on that basis.

ArgumentOutOfRangeException: Orbital period is only defined for bound (elliptical) orbits

ComputeOrbitalPeriod, ComputeMeanMotion, ComputeApsides require a > 0 and e < 1. Hyperbolic and parabolic regimes don't have a period.

ArgumentOutOfRangeException: Time step must be greater than zero

Ephemeris and finder tools require a strictly positive step. If you only want one sample, set startTime == endTime and pick any positive step.

My Find*Constraint is slow

The default coarse step is searchWindow.duration / 3000. For a yearly sweep that's about 3 hours, which is fine for coarse Earth-Moon geometry. For a fast sweep over a year you can pass stepSizeInSeconds: 3600 (or larger). Smaller is more accurate but slower.

Find*Constraint returns no windows for my propagated spacecraft

The Find*Constraint tools work on SPICE-backed items only: bodies, barycenters, Lagrange points, DSN stations from the loaded generic kernels. A spacecraft you defined via SimulateScenario is not in those kernels.

Use SimulateScenario's built-in geometryConstraints array — it evaluates constraints against the propagated trajectory in the same call.

ParseTle gives me Keplerian-looking numbers that don't reproduce a state

ParseTle returns Brouwer/Kozai mean elements, not osculating Keplerian elements. They are not interchangeable. Use EvaluateTleAtEpoch to get an osculating state vector.

Connection

My client can't reach the server

curl https://mcp.io-aerospace.org/healthz should return 200 OK from anywhere. If it doesn't, the issue is between your network and the server. If it does, the problem is in your client configuration (URL, transport type, or OAuth support).

I want to test without an LLM

Use MCP Inspector. Streamable-HTTP transport, the same URL, sign in once, then list and call tools by hand.

Getting help

Contact IO Aerospace. When reporting an issue, include:

  • Your client (Claude Desktop, Cursor, custom code, …)
  • The exact URL you configured
  • The error message, with any HTTP status code
  • Whether curl https://mcp.io-aerospace.org/healthz returns 200