MCP Server

Exoplanets Catalog exposes a read-only Model Context Protocol endpoint at /mcp so coding agents and LLM tooling can query the catalog directly.

Connection URLs:

Hosted: https://exodata.space/mcp
Local: http://127.0.0.1:3000/mcp

Transport: Streamable HTTP in stateless JSON response mode. Simple request/response clients do not need to manage MCP session IDs.

Tools

Tool	Description
`health`	Confirms the MCP server is alive.
`list_insights`	Returns curated insight metadata.
`run_insight`	Runs a curated insight by slug.
`describe_catalog`	Returns column names, descriptions, units, and data types for a table.
`query_catalog`	Runs one read-only SQL `SELECT` against `stellarhosts` and `exoplanets`.

query_catalog uses the same SQL validation and execution path as /rest/query.

Limits

Surface	Default rows	Max rows
MCP `query_catalog`	100	1000
REST `/rest/query`	1000	10000

The MCP limits are stricter on purpose: agents pull rows into context windows, so capping responses prevents one query from saturating the conversation.

Queries that fail validation, exceed the 30-second timeout, or target an unregistered table return MCP errors with a descriptive message.

Recommended Agent Flow

Call describe_catalog for the table and columns relevant to the task.
Use the returned metadata to write a SQL SELECT.
Call query_catalog with the SQL and optional limit.

Example describe_catalog arguments:

{
  "table": "exoplanets",
  "columns": ["pl_name", "hostname", "pl_rade", "pl_eqt"]
}

Example query_catalog arguments:

{
  "sql": "SELECT pl_name, hostname, pl_rade FROM exoplanets WHERE pl_rade BETWEEN 0.8 AND 1.2 ORDER BY pl_rade",
  "limit": 25
}

Join example:

{
  "sql": "SELECT s.hostname, s.st_teff, e.pl_name, e.pl_rade FROM stellarhosts s JOIN exoplanets e ON s.hostname = e.hostname ORDER BY e.pl_rade LIMIT 10"
}

Aggregate example:

{
  "sql": "SELECT discoverymethod, COUNT(*) AS count FROM exoplanets GROUP BY discoverymethod ORDER BY count DESC",
  "limit": 20
}

Connecting an Agent

The hosted endpoint speaks Streamable HTTP, so any MCP client with native HTTP transport support can connect without a local proxy. Each client uses a slightly different config file name and key.

Claude Code

Run from the project root, or --scope user for global:

claude mcp add --transport http exodata https://exodata.space/mcp

That writes .mcp.json (project scope) or ~/.claude.json (user scope):

{
  "mcpServers": {
    "exodata": {
      "type": "http",
      "url": "https://exodata.space/mcp"
    }
  }
}

Crush

.crush.json in the project root or ~/.config/crush/crush.json:

{
  "$schema": "https://charm.land/crush.json",
  "mcp": {
    "exodata": {
      "type": "http",
      "url": "https://exodata.space/mcp"
    }
  }
}

OpenCode

opencode.json in the project root or ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "exodata": {
      "type": "remote",
      "url": "https://exodata.space/mcp",
      "enabled": true
    }
  }
}

Codex CLI

Codex speaks Streamable HTTP natively. The codex mcp add CLI only covers stdio servers, so configure HTTP servers directly in ~/.codex/config.toml:

[mcp_servers.exodata]
url = "https://exodata.space/mcp"

After configuration, the agent should see five tools: health, list_insights, run_insight, describe_catalog, and query_catalog. Call health first to confirm the connection.