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 on the account page, choose New key, and copy the secret. It is shown once. The account page also 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

Add to ~/.codex/config.toml, and keep the key in your environment rather than the file:

[mcp_servers.constellation]
url = "https://api.constellation.space/mcp"
bearer_token_env_var = "CONSTELLATION_API_KEY"

export CONSTELLATION_API_KEY="<YOUR_KEY>"

Gemini CLI

Add to ~/.gemini/settings.json:

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

Grok (xAI API)

Pass Constellation as a remote MCP tool on the xAI Responses API:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4",
    "input": "Which of my ground stations are degraded right now?",
    "tools": [{
      "type": "mcp",
      "server_label": "constellation",
      "server_url": "https://api.constellation.space/mcp",
      "headers": { "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

• "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
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.

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 account page lists every limit under Plan & limits.

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.