Invariant

The agentic API provisioning layer. Your AI agent gets weather, stocks, health data, maps, and frontier LLMs from a single endpoint. invariant creates the accounts, manages the keys, enforces the quotas, and falls back when something breaks. You never touch a developer portal.

One key in. Every API out.

Why invariant exists

A useful AI agent needs to call ten different services. An LLM, a weather API, a stock ticker, a geocoder, a health database, a charity lookup. Building that today means:

• Ten developer portals, ten signup forms, ten email confirmations
• Ten API keys to rotate and secure
• Ten different auth schemes, rate limits, and error shapes
• Ten ways for a single call to fail, and no fallback when one does

invariant collapses all of it into one managed layer. You connect once over MCP or REST, and the provisioning, routing, quota accounting, and failover happen above your agent.

Provider catalog

| Provider | Category | Rate Limit | Key needed? | | ----------------------- | --------------- | ------------- | ---------------- | | OpenFDA | Physical Health | 240 req/min | No | | Mental Health Resources | Mental Health | unlimited | No | | CoinGecko | Finance | ~50 req/min | No | | Finnhub | Finance | 60 req/min | Free signup | | Every.org | Social Impact | generous | Free signup | | OpenWeatherMap | Environment | 60 req/min | Free signup | | Anthropic Claude | AI | . | Paid | | Google Gemini | AI | 1,500 req/day | Free (AI Studio) | | HuggingFace | AI | generous | Free signup | | Geoapify | Maps | 3,000 req/day | Free, no card |

On the hosted instance invariant handles every "Free signup" row for you. You never see those portals. Self-hosted instances can bring their own keys via environment variables.

How it works

         ┌─────────────────────┐
         │    Your AI Agent    │
         │  (Claude, Cursor,   │
         │   Codex, custom)    │
         └──────────┬──────────┘
                    │ MCP (JSON-RPC) or REST
                    │ single key: x-pl-key
                    ▼
         ┌─────────────────────────────────┐
         │            invariant              │
         │  ┌───────────────────────────┐  │
         │  │  auth + quota             │  │
         │  │  (Supabase + Upstash)     │  │
         │  ├───────────────────────────┤  │
         │  │  reasoning layer          │  │
         │  │  (recommend / compare)    │  │
         │  ├───────────────────────────┤  │
         │  │  provider router + fall-  │  │
         │  │  back + usage logging     │  │
         │  └───────────────────────────┘  │
         └──────────┬──────────────────────┘
                    │ managed upstream credentials
                    ▼
  OpenFDA . Mental Health . CoinGecko . Finnhub . Every.org
  OpenWeatherMap . Anthropic . Gemini . HuggingFace . Geoapify

Access modes

invariant exposes the same engine through two interfaces.

1. MCP (recommended for AI clients). JSON-RPC over HTTP at POST /api/mcp. Works with Claude Desktop, Cursor, Claude Code, Windsurf, Cline, Continue.dev, Codex CLI, Goose, and the OpenAI Responses API.

2. REST (for custom code). Plain HTTP endpoints if you are building your own integration:

| Endpoint | Method | Purpose | | ---------------- | ------ | -------------------------------------------------------- | | /api/providers | GET | List every provider and its status | | /api/query | POST | Execute an action on a provider | | /api/recommend | POST | Ask invariant to pick the best provider for a goal | | /api/usage | GET | Your current quota, tier, and per-provider breakdown | | /api/mcp | POST | MCP JSON-RPC endpoint (same tools, agent-friendly shape) |

Every endpoint requires an x-pl-key: pl_... header.

Getting started

1. Get your invariant key

Sign up at the hosted instance. You get one pl_... key. That is the only credential you ever see. Behind it, invariant is already holding every upstream account for you.

2. Connect your AI client

All clients connect to the same remote endpoint. No cloning, no building, no Node.js required.

URL:    https://pclabs.dev/api/mcp
Header: x-pl-key: pl_your_key_here

Claude Code (CLI)

claude mcp add invariant --transport http https://pclabs.dev/api/mcp --header "x-pl-key: pl_your_key_here"

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "invariant": {
      "type": "http",
      "url": "https://pclabs.dev/api/mcp",
      "headers": {
        "x-pl-key": "pl_your_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving.

claude.ai (web)

Settings → Integrations → Add custom integration. Paste the URL and set the x-pl-key header in the form. No file editing.

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "invariant": {
      "url": "https://pclabs.dev/api/mcp",
      "headers": {
        "x-pl-key": "pl_your_key_here"
      }
    }
  }
}

Or via UI: Settings → Tools & Integrations → MCP → Add Server.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "invariant": {
      "url": "https://pclabs.dev/api/mcp",
      "headers": {
        "x-pl-key": "pl_your_key_here"
      }
    }
  }
}

Or via UI: Cascade panel → MCP Servers → Configure.

Cline (VS Code extension)

1. Open the Cline sidebar
2. Click the MCP Servers tab (plug icon)
3. Add Server → HTTP
4. Paste https://pclabs.dev/api/mcp as the URL
5. Add header x-pl-key: pl_your_key_here

Continue.dev

Edit ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "invariant",
      "transport": {
        "type": "http",
        "url": "https://pclabs.dev/api/mcp",
        "headers": {
          "x-pl-key": "pl_your_key_here"
        }
      }
    }
  ]
}

OpenAI Codex CLI

Edit ~/.codex/config.toml:

[mcp_servers.invariant]
type = "http"
url = "https://pclabs.dev/api/mcp"

[mcp_servers.invariant.headers]
x-pl-key = "pl_your_key_here"

OpenAI Responses API

Pass the MCP server directly as a tool:

response = client.responses.create(
    model="codex-mini-latest",
    tools=[{
        "type": "mcp",
        "server_url": "https://pclabs.dev/api/mcp",
        "headers": { "x-pl-key": "pl_your_key_here" }
    }],
    input="What crypto prices are available?"
)

Goose (Block)

Edit ~/.config/goose/config.yaml:

extensions:
  invariant:
    type: mcp
    enabled: true
    transport: http
    url: https://pclabs.dev/api/mcp
    headers:
      x-pl-key: pl_your_key_here

MCP tools

The MCP endpoint exposes four tools.

recommend

Describe what you need. invariant returns ranked providers with scores, reasoning, pricing, and availability. This is the agentic entry point. Agents should start here, not with query.

{
  "need": "real-time crypto prices with no signup",
  "priorities": ["no-auth", "cost"],
  "budget": "free"
}

compare

Side-by-side comparison of two or more providers on pricing, rate limits, strengths, and weaknesses.

{ "provider_ids": ["claude", "gemini"] }

list_providers

Browse the catalog, optionally filtered by category: physical_health, mental_health, financial, social_impact, environment, ai, maps.

query

Execute a specific action against a specific provider. The low-level primitive that recommend ultimately calls into.

{
  "provider_id": "coingecko",
  "action": "price",
  "params": { "ids": "bitcoin", "vs_currencies": "usd" }
}

Self-hosting

You can run your own invariant instance if you want to bring your own upstream credentials or host on your own infrastructure.

Prerequisites

• Node.js 18+
• A Supabase project for accounts and usage logging. See migration.sql for the schema.
• An Upstash Redis instance for per-minute rate limiting

Deploy to Railway

invariant runs as a single Node HTTP server defined in dev-server.ts, which mounts the route handlers in api/ plus the admin, signup, and waitlist routes. Railway auto-detects the start script, so no railway.toml or Procfile is required.

npm install
npm run build
npm start     # runs dist/dev-server.js on $PORT

Point Railway at this repo and set the environment variables below in the Railway dashboard.

Environment variables

Platform (required):

| Variable | Description | | -------------------------- | -------------------------------------------- | | SUPABASE_URL | Supabase project URL | | SUPABASE_SERVICE_KEY | Supabase service role key (server-side only) | | UPSTASH_REDIS_REST_URL | Upstash Redis REST URL | | UPSTASH_REDIS_REST_TOKEN | Upstash Redis REST token | | ADMIN_PASSWORD | Password gate for the admin API endpoints |

Upstream providers (optional). Omit a variable to disable that provider:

| Variable | Provider | | ----------------------- | -------------------------------------------------------------------------------------- | | ANTHROPIC_API_KEY | Anthropic Claude (console.anthropic.com) | | GOOGLE_GEMINI_API_KEY | Google Gemini (aistudio.google.com) | | HUGGINGFACE_API_KEY | HuggingFace (huggingface.co/settings/tokens) | | FINNHUB_API_KEY | Finnhub (finnhub.io) | | COINGECKO_API_KEY | CoinGecko. Optional, boosts rate limit. | | EVERY_ORG_API_KEY | Every.org (partners.every.org) | | OPENWEATHER_API_KEY | OpenWeatherMap (openweathermap.org/api) | | GEOAPIFY_API_KEY | Geoapify (myprojects.geoapify.com) | | OPENFDA_API_KEY | OpenFDA. Optional, boosts rate limit. |

Providers without a configured key show Status: Not configured in list_providers and return a 503 when queried. OpenFDA and Mental Health Resources work with no key at all.

Provisioning keys

Keys live in Supabase, not in an env var. Apply migration.sql to your project to create the accounts and usage tables, then create accounts through the admin endpoints (gated by ADMIN_PASSWORD) or by inserting rows directly. Each account row holds a pl_... key, a tier, a monthly quota, and a per-minute rate.

Local development

cp .env.example .env          # fill in your values
npm install
npx tsx dev-server.ts         # HTTP server with hot-restart via tsx

The server listens on $PORT (defaults to 3000). Hit http://localhost:3000/api/providers with your x-pl-key header to sanity check.

To run the stdio MCP fallback instead (see below), use npm run dev.

Fallback: local stdio MCP

For MCP clients that cannot speak HTTP, the repo also ships a thin stdio proxy in src/ that forwards to a remote invariant backend:

npm install
npm run build

{
  "mcpServers": {
    "invariant": {
      "command": "node",
      "args": ["/absolute/path/to/invariant/dist/index.js"],
      "env": {
        "PL_API_KEY": "pl_your_key_here",
        "PL_BACKEND_URL": "https://pclabs.dev/api/mcp"
      }
    }
  }
}

MCP client env vars for the stdio path:

| Variable | Required | Description | | ---------------- | -------- | ----------------------------------------------------------- | | PL_API_KEY | Yes | Your pl_ key | | PL_BACKEND_URL | No | Override backend URL. Default: https://pclabs.dev/api/mcp |

Adding a provider

1. Create lib/providers/my-provider.ts implementing the Provider interface from lib/providers/types.ts
2. Register it in lib/providers/registry.ts
3. Add any required env vars to .env.example
4. Add metadata to lib/reasoning/ so the recommend tool can surface it

Scripts

npm run dev    # stdio MCP server via tsx, no build
npm run build  # compile TypeScript → dist/
npm start      # run compiled standalone server (dist/dev-server.js)
npm test       # run test.ts against local backend

Built on MCP, Hono, Supabase, and Upstash Redis.