Saturn MCP connector

The connector exposes a small toolbox to MCP clients:

• saturn_list_projects — every project across your workspaces.
• saturn_get_project — stage, plan summary, latest checkpoint, and live deploy URLs.
• saturn_list_build_files + saturn_read_build_file — JSON config artifacts in the latest checkpoint.
• saturn_recent_errors + saturn_recent_logs — the last 50–200 entries from the running app.
• saturn_whoami — sanity-check which account a token belongs to.

Plus seven BYOK capability tools — active only when you've added the relevant provider key at Settings → API keys:

• deep_think — Anthropic Opus 4.7 with adaptive thinking for hard reasoning problems.
• generate_image — OpenAI gpt-image-1.5 image generation, returns base64.
• analyze_long_document — Google Gemini with up to 1M-token context (auto-routes Flash ↔ Pro).
• research_web — Perplexity cited web research with source URLs.
• current_events — xAI Grok with live X + web search for real-time signal.
• generate_voice — ElevenLabs text-to-speech, returns base64 MP3.
• bulk_classify — DeepSeek flash JSON-mode classification at cost-floor pricing.

Writes (creating plans, deploying, mutating secrets) are intentionally out of scope. Saturn is billed zero markup on BYOK calls — your provider account is charged directly.

The seven capability tools each need a provider key from your own account — Saturn never charges markup on these calls. Go to Settings → API keys → Provider keys and paste in whichever provider keys you want to use. You can skip any provider and add it later; the tool will return a clear error if the key is missing rather than silently failing.

Visit Settings → API keys and create a new key. Give it a label that names where you'll paste it, e.g. claude.ai web or Claude Code on laptop. The full token is shown exactly once — copy it before dismissing the banner. We store only its sha256.

In Claude.ai, open Settings → Connectors → Add custom connector. Use these values:

URL:    https://saturnos.app/api/mcp
Auth:   Bearer token
Token:  <paste your Saturn key>

Save, then start a new chat. Ask Claude to list your Saturn projects to confirm the handshake worked.

Run this in any terminal:

claude mcp add --transport http saturn \
  https://saturnos.app/api/mcp \
  --header "Authorization: Bearer YOUR_KEY"

Then ask Claude Code something like “what's breaking on my saturn project today?” and it will pull recent errors from saturn_recent_errors.

Each key is bound to the Saturn user that minted it. Tools scope every query to projects in workspaces you're a member of — adding the connector to Claude does not expose anyone else's data. Revoking a key in Settings → API keys takes effect on the next request.

Keys live in our database as sha256 hashes. We can't recover a lost token — mint a new one. last_used_at is stamped on each successful call so you can spot stale or unused keys.

The connector is a Model Context Protocol server speaking the streamable-http transport (revision 2025-06-18, with 2025-03-26 negotiated for older clients). JSON-RPC 2.0 over POST; GET returns a manifest for humans. Auth is bearer-token via the Authorization header (or X-Api-Key as a fallback).

Curious? Hit the manifest from a terminal:

curl https://saturnos.app/api/mcp