Claude Code ← custom plugin API
Cursor     ← different extension API
Aider      ← different command format
Custom Go agent ← different RPC protocol

Every agent → MCP protocol → Every tool server

# 1. Clone and install
git clone https://github.com/SuperInstance/superinstance-mcp.git
cd superinstance-mcp
npm install

# 2. Verify the server works
npx tsx src/index.ts
# Output: [SuperInstance MCP] Server started — 8 tools available

# 3. Test a tool call (raw JSON-RPC)
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"conservation_check","arguments":{"gamma":0.8,"eta":0.5}},"id":1}' | \
  npx tsx src/index.ts 2>/dev/null | python3 -m json.tool

# 4. Install for your agent (pick one):
./install.sh                    # Claude Code (global)
cp .mcp.json ~/.cursor/mcp.json # Cursor
# See platform-specific instructions below

./install.sh
# Writes to ~/.claude/.mcp.json

cp .mcp.json /your/project/.mcp.json

// ~/.claude/.mcp.json
{
  "mcpServers": {
    "superinstance": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/superinstance-mcp/src/index.ts"],
      "env": {
        "FLEET_API_URL": "https://fleet-dashboard-api.casey-digennaro.workers.dev",
        "VECTOR_API_URL": "https://fleet-vector-api.casey-digennaro.workers.dev"
      }
    }
  }
}

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "superinstance": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/superinstance-mcp/src/index.ts"],
      "env": {
        "FLEET_API_URL": "https://fleet-dashboard-api.casey-digennaro.workers.dev",
        "VECTOR_API_URL": "https://fleet-vector-api.casey-digennaro.workers.dev"
      }
    }
  }
}

This project uses SuperInstance conservation-law governance.
Before writing code, use fleet_search to find existing patterns.
After writing code, use conservation_check to verify invariants.
All signal-processing code must pass ternary_validate.

// VS Code settings.json or Cline's MCP settings
{
  "mcpServers": {
    "superinstance": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/superinstance-mcp/src/index.ts"],
      "disabled": false,
      "autoApprove": [
        "fleet_status",
        "fleet_search",
        "fleet_budget",
        "conservation_check",
        "ternary_validate",
        "crate_info",
        "fleet_agents",
        "ecosystem_stats"
      ]
    }
  }
}

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "superinstance": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/superinstance-mcp/src/index.ts"]
    }
  }
}

// Goose session config
{
  "tools": {
    "mcpServers": {
      "superinstance": {
        "command": "npx",
        "args": ["tsx", "/absolute/path/to/superinstance-mcp/src/index.ts"]
      }
    }
  }
}

gooose mcp add superinstance -- npx tsx /absolute/path/to/superinstance-mcp/src/index.ts

// Q Developer MCP config
{
  "mcpServers": {
    "superinstance": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/superinstance-mcp/src/index.ts"]
    }
  }
}

// .zed/settings.json (project-level) or ~/.zed/settings.json (global)
{
  "mcp": {
    "servers": {
      "superinstance": {
        "command": "npx",
        "args": ["tsx", "/absolute/path/to/superinstance-mcp/src/index.ts"]
      }
    }
  }
}

// ~/.continue/config.json
{
  "mcpServers": {
    "superinstance": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/superinstance-mcp/src/index.ts"]
    }
  }
}

# Wrapper script: ~/bin/fleet
#!/bin/bash
echo "{\"jsonrpc\":\"2.0\",\"method\":\"tools/call\",\"params\":{\"name\":\"$1\",\"arguments\":$2}},\"id\":1}" | \
  npx tsx /path/to/superinstance-mcp/src/index.ts 2>/dev/null | \
  jq -r '.result.content[0].text'

# In aider session:
!/bin/fleet conservation_check '{"gamma":0.8,"eta":0.5}'
!/bin/fleet fleet_status '{}'
!/bin/fleet fleet_search '{"query":"rate limiter","topK":3}'

# .aider.conf.yml
commands:
  fleet-status: "!/bin/fleet fleet_status '{}'"
  fleet-search: "!/bin/fleet fleet_search '{\"query\":\"$ARGS\"}'"

pip install mcp

import asyncio
import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

MCP_PATH = "/path/to/superinstance-mcp/src/index.ts"

async def main():
    params = StdioServerParameters(
        command="npx",
        args=["tsx", MCP_PATH],
        env={
            "FLEET_API_URL": "https://fleet-dashboard-api.casey-digennaro.workers.dev",
        }
    )

    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Discover available tools
            tools = await session.list_tools()
            for tool in tools.tools:
                print(f"  {tool.name}: {tool.description[:80]}...")

            # Check fleet status
            result = await session.call_tool("fleet_status", {})
            status = json.loads(result.content[0].text)
            print(f"\nFleet: {status['conservation']['status']}")
            print(f"Agents: {status['agents']['active']} active")

            # Semantic search
            result = await session.call_tool("fleet_search", {
                "query": "ternary PID controller",
                "topK": 3
            })
            data = json.loads(result.content[0].text)
            for r in data.get("results", []):
                print(f"  - {r.get('name')}: {r.get('description', '')[:60]}")

            # Conservation check
            result = await session.call_tool("conservation_check", {
                "gamma": 0.9,
                "eta": 0.5
            })
            check = json.loads(result.content[0].text)
            print(f"\nConservation: {check['valid']} — {check['message']}")

asyncio.run(main())

go get github.com/ThinkInAIXYZ/go-mcp

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "github.com/ThinkInAIXYZ/go-mcp/client"
    "github.com/ThinkInAIXYZ/go-mcp/protocol"
)

func main() {
    c, err := client.NewStdioClient(
        "npx", "tsx", "/path/to/superinstance-mcp/src/index.ts",
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // List tools
    tools, _ := c.ListTools(ctx)
    for _, tool := range tools {
        fmt.Printf("  %s\n", tool.Name)
    }

    // Check conservation
    raw, _ := c.CallTool(ctx, "conservation_check", map[string]any{
        "gamma": 0.8,
        "eta":   0.5,
    })

    var result struct {
        Valid   bool    `json:"valid"`
        Message string  `json:"message"`
        Delta   float64 `json:"delta"`
    }
    json.Unmarshal([]byte(raw.Content[0].Text), &result)
    fmt.Printf("Valid: %v, δ=%.4f\n%s\n", result.Valid, result.Delta, result.Message)
}

# Cargo.toml
[dependencies]
mcp-client = "0.1"
tokio = { version = "1", features = ["full"] }
serde_json = "1"

use mcp_client::{Client, StdioTransport};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let transport = StdioTransport::new(
        "npx", &["tsx", "/path/to/superinstance-mcp/src/index.ts"],
    );

    let mut client = Client::new(transport);
    client.initialize().await?;

    // List all 8 tools
    let tools = client.list_tools().await?;
    for tool in &tools {
        println!("  {}: {}", tool.name, tool.description);
    }

    // Check fleet status
    let result = client
        .call_tool("fleet_status", json!({}))
        .await?;
    println!("{}", result.content[0].text);

    Ok(())
}

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['tsx', '/path/to/superinstance-mcp/src/index.ts'],
});

const client = new Client(
  { name: 'my-agent', version: '1.0.0' },
  { capabilities: {} }
);

await client.connect(transport);

// List tools
const tools = await client.listTools();
console.log(`${tools.tools.length} tools available`);

// Call conservation_check
const result = await client.callTool({
  name: 'conservation_check',
  arguments: { gamma: 0.9, eta: 0.5 },
});
console.log(JSON.parse((result.content as any)[0].text));

await client.close();

"""
Use SuperInstance fleet tools within an OpenAI Agents SDK workflow.
"""
from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async def main():
    # Create MCP server connection
    fleet_server = MCPServerStdio(
        command="npx",
        args=["tsx", "/path/to/superinstance-mcp/src/index.ts"],
    )
    await fleet_server.connect()

    # Agent with fleet tools
    fleet_agent = Agent(
        name="Fleet Coordinator",
        instructions="""You manage a SuperInstance fleet. Before any task:
        1. Call fleet_status to check fleet health
        2. Call fleet_search to find existing solutions
        3. Call conservation_check before proposing changes
        """,
        mcp_servers=[fleet_server],
    )

    result = await Runner.run(fleet_agent, "Check fleet status and find rate limiter patterns")
    print(result.final_output)

    await fleet_server.cleanup()

"""
Use SuperInstance MCP tools as LangGraph nodes.
"""
from langgraph.prebuilt import create_react_agent
from langchain_mcp_adapters.client import MultiServerMCPClient

async def create_fleet_agent():
    client = MultiServerMCPClient({
        "superinstance": {
            "command": "npx",
            "args": ["tsx", "/path/to/superinstance-mcp/src/index.ts"],
            "transport": "stdio",
        }
    })

    tools = await client.get_tools()

    agent = create_react_agent(
        tools=tools,
        model="gpt-4o",
        prompt="""You are a fleet-aware agent. Use conservation_check before
        proposing architectural changes. Use fleet_search to find existing patterns.""",
    )

    return agent

"""
SuperInstance tools as CrewAI agent tools.
"""
from crewai import Agent, Task, Crew
from crewai.tools import MCPServerAdapter

# Connect to MCP server
with MCPServerAdapter(
    command="npx",
    args=["tsx", "/path/to/superinstance-mcp/src/index.ts"],
) as tools:

    fleet_agent = Agent(
        role="Fleet Governor",
        goal="Ensure all tasks comply with the conservation law γ + η ≤ C",
        backstory="An AI agent that enforces physics-grounded governance.",
        tools=tools,
        verbose=True,
    )

    status_task = Task(
        description="Check fleet status and find patterns for implementing a rate limiter",
        agent=fleet_agent,
        expected_output="Fleet status summary and relevant crate recommendations",
    )

    crew = Crew(agents=[fleet_agent], tasks=[status_task])
    result = crew.kickoff()
    print(result)

FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build
# Server reads JSON-RPC from stdin, writes to stdout
CMD ["node", "dist/index.js"]

docker build -t superinstance-mcp .
# The container reads JSON-RPC from stdin
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | docker run -i superinstance-mcp 2>/dev/null

services:
  agent:
    build: .
    environment:
      - MCP_SERVER_COMMAND=docker
      - MCP_SERVER_ARGS=run -i superinstance-mcp

// Any MCP client can connect via HTTP
const transport = new StreamableHTTPClientTransport(
  new URL('https://superinstance-mcp-remote.your-account.workers.dev')
);
const client = new Client({ name: 'remote-agent', version: '1.0' }, { capabilities: {} });
await client.connect(transport);

// Response
{
  "source": "live-api",  // or "static-fallback"
  "conservation": {
    "C": 1.584962500721156,
    "C_approx": 1.585,
    "gamma_total": 1.45,
    "eta_total": 1.44,
    "remaining": -1.305,
    "utilization": "183%",
    "status": "❌ VIOLATED"
  },
  "agents": { "count": 5, "active": 4, "standby": 1 },
  "convergence": {
    "delta": 0.3887,
    "formula": "δ(n) = (1/√n)(1 - 3/(2n))",
    "n": 5
  }
}

// Call
{ "query": "how does the conservation law relate to Shannon entropy", "topK": 3 }

// Response (tries SHOAL → Vector API → local fallback)
{
  "source": "shoal-local",  // or "fleet-vector-api" or "local-fallback"
  "query": "how does the conservation law relate to Shannon entropy",
  "results": [
    { "rank": 1, "name": "conservation-law", "score": 0.95, "description": "..." },
    { "rank": 2, "name": "noether-bridge", "score": 0.82, "description": "..." }
  ]
}

// Call
{ "gamma_used": 0.8, "eta_produced": 0.6 }

// Response
{
  "gamma_used": 0.8,
  "eta_produced": 0.6,
  "c_capacity": 1.585,
  "total_used": 1.4,
  "remaining": 0.185,
  "utilization_pct": 88.3,
  "status": "✅ BUDGET AVAILABLE"
}

// Call
{ "gamma": 0.9, "eta": 0.5 }

// Response (δ > 0.5)
{ "valid": true, "delta": 0.185, "message": "✅ CONSERVED. Healthy headroom." }

// Response (δ < 0)
{ "valid": false, "delta": -0.315, "message": "❌ VIOLATED. Over by 0.315." }

// Call
{ "values": [1, -1, 0, 1, 0, -1, 0.5] }

// Response
{
  "valid": false,
  "count": 7,
  "invalid_count": 1,
  "invalid_values": [0.5],
  "message": "❌ 1 of 7 values not in {-1, 0, +1}: [0.5]"
}

// Call
{ "name": "shoal" }

// Response
{
  "name": "shoal",
  "version": "0.3.2",
  "description": "Ternary oracle runtime...",
  "repo": "https://github.com/SuperInstance/shoal",
  "conservation_role": "Oracle: converts ternary signals to bounded predictions via γ + η ≤ C"
}

// Response
{
  "count": 5,
  "active": 4,
  "agents": [
    {
      "name": "phoenix",
      "role": "builder",
      "phase": "active",
      "gamma": 0.38,
      "eta": 0.44,
      "status": "✅ CONSERVED",
      "crates": ["wavefront", "fleet-vector-api"],
      "workers": 6
    }
  ]
}

{
  "crates": 25,
  "workers": 12,
  "repos": 18,
  "tests": 847,
  "theorems_proven": 1,
  "conservation_law": "γ + η ≤ C where C = log₂(3) ≈ 1.585",
  "conservation_constant": { "symbol": "C", "value": 1.585, "formula": "log₂(3)" }
}

γ + η ≤ C    where C = log₂(3) ≈ 1.585 bits

┌─────────────────────────────────────────────────────────────────────┐
│                      Any MCP Client                                  │
│                                                                     │
│  Claude Code · Cursor · Cline · Windsurf · Goose · Amazon Q · Zed  │
│  OpenAI Agents · LangGraph · CrewAI · AutoGen · Custom Agents       │
└────────────────────────────────┬────────────────────────────────────┘
                                 │
                    MCP Protocol (JSON-RPC 2.0)
                    stdio (local) or HTTP (remote)
                                 │
              ┌──────────────────▼──────────────────┐
              │     superinstance-mcp Server        │
              │     (TypeScript, 683 LOC)           │
              │                                    │
              │   ┌─────────────────────────────┐   │
              │   │       8 MCP Tools           │   │
              │   │  • Always returns data      │   │
              │   │  • 5s timeout on network    │   │
              │   │  • Static fallbacks         │   │
              │   │  • Conservation-gated       │   │
              │   └─────────────────────────────┘   │
              └──────────────┬──────────────────────┘
                             │ HTTP (optional)
           ┌─────────────────┼─────────────────┐
           │                 │                 │
  ┌────────▼───────┐ ┌──────▼───────┐ ┌───────▼────────┐
  │  Fleet         │ │  SHOAL       │ │  Fleet Vector  │
  │  Dashboard API │ │  Oracle      │ │  API           │
  │ (CF Worker)    │ │ (CF Worker)  │ │ (CF Worker)    │
  └────────┬───────┘ └──────┬───────┘ └───────┬────────┘
           │                 │                 │
  ┌────────▼─────────────────▼─────────────────▼──────┐
  │              Cloudflare Edge                       │
  │     D1 · KV · Vectorize · Workers AI · Queues     │
  └───────────────────────────────────────────────────┘

Agent instructions:
"Before proposing any architecture, call conservation_check with estimated
γ (coordination cost) and η (entropy produced). Only propose solutions
where δ = C − γ − η > 0.1."

Agent instructions:
"Before writing new code, call fleet_search with your intended feature.
If results exist, use them as reference. Only write new code if no
existing pattern matches (similarity score < 0.5)."

# Assign tasks to agents based on remaining conservation budget
agents = call("fleet_agents")
for task in tasks:
    for agent in agents:
        if agent.remaining_budget >= task.cost:
            assign(task, agent)
            break

# Block deploys that violate conservation
RESULT=$(echo '{"jsonrpc":"2.0",...}' | npx tsx mcp/index.ts)
VALID=$(echo "$RESULT" | jq '.valid')
[ "$VALID" = "true" ] || exit 1

# An autonomous agent that checks budget before every action
async def act(agent, action):
    budget = await mcp.call("fleet_budget", {
        "gamma_used": agent.gamma_total + action.gamma_cost,
        "eta_produced": agent.eta_total + action.eta_expected
    })
    if "✅" in budget["status"]:
        await execute(action)
    else:
        await queue(action)  # Wait for budget

npm install
npm run dev  # tsx with watch mode

npm run build
node dist/index.js

docker build -t superinstance-mcp .
echo '{...}' | docker run -i superinstance-mcp

npx wrangler deploy --name superinstance-mcp-remote
# Connect from anywhere: https://superinstance-mcp-remote.your-account.workers.dev

git clone https://github.com/SuperInstance/superinstance-mcp.git
cd superinstance-mcp
npm install
npm run dev