SkyFi MCP Server

Official Model Context Protocol server for the SkyFi satellite imagery platform. Enables any AI agent to search, price, order, and monitor satellite imagery through conversational tool calls.

Quick Start (< 10 minutes)

1. Install

npm install skyfi-mcp@0.1.0

2. Configure

Create ~/.skyfi/config.json:

{ "api_key": "sk_your_skyfi_api_key" }

Or set the environment variable:

export SKYFI_API_KEY=sk_your_key

3. Run (Local STDIO)

npx skyfi-mcp

4. Connect

Claude Code / Claude Desktop:

{
  "mcpServers": {
    "skyfi": {
      "command": "npx",
      "args": ["skyfi-mcp"],
      "env": { "SKYFI_API_KEY": "sk_your_key" }
    }
  }
}

Claude.ai (remote MCP — no install needed):

1. Open Claude.ai → Settings → Integrations → Add MCP Server
2. Enter the server URL: https://skyfi-mcp.skyfi-xian.workers.dev/mcp
3. Add your SkyFi API key as a custom header: X-SkyFi-API-Key: sk_your_key
4. Save — Claude will automatically exchange your key for a session token

Remote (any framework):

# First request: send your API key to get a session token
POST https://skyfi-mcp.skyfi-xian.workers.dev/mcp
Header: X-SkyFi-API-Key: sk_your_key
→ Response includes X-MCP-Token header

# All subsequent requests: use the session token
POST https://skyfi-mcp.skyfi-xian.workers.dev/mcp
Header: X-MCP-Token: mcp_sess_<your_token>

Your raw API key is only sent once. The session token has a 4-hour idle TTL (extends on each request) and 7-day max lifetime.

Standout Differentiators

• Reliability scorecard: generated operational snapshot at mcp-docs/STATUS.md (npm run status:refresh)
• Golden demo workflow: maritime monitoring showcase at mcp-docs/GOLDEN_DEMO_MARITIME.md
• Cost intelligence tool: recommend_archive_purchase ranks options by price/quality strategy with budget filtering

Authentication

Token Exchange (Remote)

The remote server uses a token exchange model to protect your SkyFi API key:

1. Initialize — Send X-SkyFi-API-Key on your first request. The server validates it and returns an X-MCP-Token session token.
2. Use — All subsequent requests use X-MCP-Token. Your raw API key never appears in agent traffic again.
3. Expire — Session tokens expire after 4 hours idle or 7 days max. Re-send your API key to get a new one.

Service Tokens (Pipelines)

For automated pipelines that run unattended, create a long-lived service token:

# Call the create_service_token tool with an active session
→ Returns: mcp_svc_<token> (90-day lifetime, no idle expiry)

Service tokens support optional scopes (restrict which tools can be called) and budget caps (server-side spend limits).

Local (STDIO)

Local mode reads your API key from ~/.skyfi/config.json or SKYFI_API_KEY env var at startup. No token exchange needed.

Tools (19)

Category	Tools
Geocoding	geocode, reverse_geocode, get_bounding_box
Discovery	search_archive, explore_open_data
Pricing	estimate_archive_price, estimate_tasking_cost, check_capture_feasibility
Cost Intelligence	recommend_archive_purchase
Ordering	quote_archive_order, execute_archive_order, quote_tasking_order, execute_tasking_order
History	get_order_status, list_orders, fetch_order_image
Monitoring	setup_aoi_monitoring, create_webhook_subscription, get_notification_status

Order Safety

Orders use a two-step confirmation flow enforced server-side:

1. Quote → returns price and quote_id (valid 15 min)
2. Execute → requires quote_id + user_confirmed: true + idempotency_key

The execute_* tools cannot be called without all three fields. This is enforced at the schema level and cannot be bypassed by prompt injection.

Security

• API key protection — Raw key sent once, exchanged for scoped token. Key encrypted at rest (AES-256-GCM) with derived keys (HKDF).
• Key hashing — Usage metrics use HMAC-SHA-256 with a separate derived key. Not reversible without the server secret.
• Per-request isolation — Each request creates an independent SkyFi client. No shared mutable auth state. One tenant's credentials cannot leak to another.
• Rate limiting — Per-key: 100 calls/min, 20/10s burst. Daily caps: 10 orders, $10K spend.
• Service token scoping — Optional tool restrictions and budget caps, enforced server-side.
• Prompt injection defense — All inputs treated as data. String length caps (500 chars). Control character stripping. Order confirmation enforced server-side, not in prompts.

Framework Support

Framework	Transport	Guide
Google ADK	STDIO / HTTP+SSE	docs/integrations/google-adk.md
LangChain / LangGraph	STDIO / HTTP+SSE	docs/integrations/langchain.md
Vercel AI SDK	HTTP+SSE	docs/integrations/vercel-ai-sdk.md
Claude Web	HTTP+SSE	docs/integrations/claude-web.md
OpenAI	HTTP+SSE	docs/integrations/openai.md
Claude Code	STDIO / HTTP+SSE	docs/integrations/claude-code.md
Gemini	HTTP+SSE	docs/integrations/gemini.md

Compatibility matrix and transport expectations: docs/integrations/COMPATIBILITY.md

Simulation Mode

Test the full order flow without placing real orders:

SKYFI_SIMULATE=true npx skyfi-mcp

Or per-request: pass "simulate": true in quote/execute tool calls.

Deployment

Cloudflare Workers (live):

https://skyfi-mcp.skyfi-xian.workers.dev/mcp

Self-deploy:

npx wrangler deploy

Docker:

docker compose up

Development

npm install
npm run build        # Build with tsup
npm test             # Run test suite
npm run typecheck    # TypeScript check
npm run lint         # ESLint

License

MIT