Connect an AI agent (MCP)

Constellation runs a remote Model Context Protocol (MCP) server. Point your agent at it with an API key, and the agent can read your topology, ask for predictions, and send telemetry on your behalf, inside the same limits and tenant isolation as the REST API.

Setting	Value
Server URL	https://api.constellation.space/mcp
Transport	Streamable HTTP
Authentication	Authorization: Bearer <YOUR_KEY>

1. Create a key

Sign in to Platform, choose Create live key, and copy the secret. It is shown once. The Agents page fills your new key into every configuration below.

2. Add the server to your agent

Claude Code

claude mcp add --transport http constellation https://api.constellation.space/mcp \
  --header "Authorization: Bearer <YOUR_KEY>"

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit config), then restart Claude Desktop. Requires Node.js.

{
  "mcpServers": {
    "constellation": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.constellation.space/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer <YOUR_KEY>" }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "constellation": {
      "url": "https://api.constellation.space/mcp",
      "headers": { "Authorization": "Bearer <YOUR_KEY>" }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "constellation": {
      "type": "http",
      "url": "https://api.constellation.space/mcp",
      "headers": { "Authorization": "Bearer <YOUR_KEY>" }
    }
  }
}

Codex CLI

Run in your terminal. The key stays in your environment, not in the config file:

export CONSTELLATION_API_KEY="<YOUR_KEY>"
codex mcp add constellation --url https://api.constellation.space/mcp --bearer-token-env-var CONSTELLATION_API_KEY

Gemini CLI

Run in your terminal. The key stays in your environment, not in the config file:

export CONSTELLATION_API_KEY="<YOUR_KEY>"
gemini mcp add --scope user --transport http constellation https://api.constellation.space/mcp --header 'Authorization: Bearer $CONSTELLATION_API_KEY'

Gemini loads MCP servers only in folders you trust.

Grok Build

Run in your terminal:

grok mcp add --transport http constellation https://api.constellation.space/mcp --header "Authorization: Bearer <YOUR_KEY>"

ChatGPT and claude.ai

Their built-in web connectors sign in with OAuth, which the Constellation MCP server does not offer yet. Use Claude Desktop or Claude Code in the meantime.

3. Ask your agent

• "Load the demo fleet, then tell me which demand pool will be under the most pressure over the next hour."
• "Load the demo fleet and list my ground stations with the demand pool each one serves."
• "Forecast SNR for the links at Randolph Ridge over the next 5 minutes and flag anything under 22 dB."
• "Which of my ground stations carries its demand pool alone, and how close is it to its busiest interval?"
• "Which of my ground stations are degraded right now?"
• "Forecast SNR on my busiest link for the next hour."
• "How many prediction calls do I have left this month?"

Tools

Tool	What it does
load_demo_fleet	Loads a ready-made demo fleet into your account: 6 ground stations, 39 satellites, 21 links with two hours of SNR telemetry, and 4 demand pools with seven days of history. Safe to repeat. Needs the telemetry:write scope.
get_topology	Current state of your fleet: ground stations, satellites, and links.
get_predictions	Forecasts for named links, such as SNR over the next pass.
send_telemetry	Write telemetry records for your entities.
get_usage	Your plan, and how much of this month's allowance is used.

No fleet yet? Start with the demo fleet

A new account has no data, so ask the agent to call load_demo_fleet first. It writes a recorded fleet into your account ending at the present, so get_topology and get_predictions work straight away. The demo data does not advance on its own: forecasts need recent telemetry (the last minute for SNR, the last ten minutes for demand), so have the agent call load_demo_fleet again right before get_predictions. Demand in the demo fleet is synthetic, not measured traffic. Loading costs no predictions; each forecast call spends one, as usual. Forecast a few links per call (five or fewer): forecasts are computed on demand, and links that cannot be computed yet come back as prediction_unavailable with a hint to retry shortly.

Limits

The MCP server spends the same allowance as the REST API. On the free plan that is 10 prediction calls per month; telemetry and topology are not capped. Ask the agent for get_usage, or call GET /account/state with your key, to see what is left this month; the Usage page shows usage against your plan allowance.

Troubleshooting

Symptom	Cause	Fix
401 or "unauthorized"	The key is missing, mistyped, or revoked.	Check the Authorization: Bearer header, or create a new key.
quota_exceeded from get_predictions	This month's free prediction allowance is used.	Wait for the reset date in the error, or upgrade on the account page.
The agent lists no Constellation tools	The client did not load the config.	Restart the client after editing its config file.

Keep agent configuration files private: anyone holding the key can act as you. Revoke a key on the account page and it stops working everywhere.