Platform MCP server

Connect from Claude Code

$ claude mcp add --transport http blobfish-twins https://blobfish.ai/api/v1/twin/mcp \
    --header "x-api-key: $BLOBFISH_API_KEY"

# no key yet?
$ blobfish login            # mints a bf_ key into ~/.blobfish/config
$ export BLOBFISH_API_KEY=bf_…

Streamable HTTP, one JSON-RPC message per request, JSON responses. The key rides in the x-api-key header (Authorization: Bearer bf_… also works) and never in a tool argument. Against a local checkout use http://localhost:3000/api/v1/twin/mcp.

{
  "mcpServers": {
    "blobfish-twins": {
      "url": "https://blobfish.ai/api/v1/twin/mcp",
      "headers": { "x-api-key": "${BLOBFISH_API_KEY}" }
    }
  }
}

Adapt the field names your client uses for a remote HTTP server and its headers; the URL and the x-api-key header are the whole configuration.

Tools

13 tools; 12 need your key. The table is rendered from the registry the server serves — tools/list returns exactly these names and schemas.

An agent session

# 1 · the agent provisions a Salesforce twin
tools/call provision_twins
  {"twins": ["salesforce"], "ttl_minutes": 60, "name": "CRM agent test"}
→ env_id: twe_9246107c29038f60 · status: ready · mounted_services: [salesforce]
  routing.services[0].mcp_url:      https://blobfish.ai/api/v1/sandbox/worlds/sbx_…/services/salesforce/mcp
  routing.services[0].rest_base_url: https://blobfish.ai/api/v1/sandbox/worlds/sbx_…/services/salesforce/rest
  routing.console_url:              https://blobfish.ai/twin/twe_9246107c29038f60

# 2 · it runs a model against the seeded twin (keys come from the server or your saved provider)
tools/call run_model_on_twin
  {"env_id": "twe_9246107c29038f60", "model": "claude-sonnet-5",
   "prompt": "List the open opportunities and close the smallest one as won.", "max_steps": 8}
→ run_id: twrun_… · status: completed · finish: final · model.credential_source: server
  steps[0].tool: salesforce_opportunities_list · steps[1].tool: salesforce_opportunities_update
  final_answer: "Closed Veyra Logistics – renewal ($12,400) as Closed Won."

# 3 · it tears the environment down when done (delists; the world is never destroyed)
tools/call teardown_twin_environment
  {"env_id": "twe_9246107c29038f60"}
→ ok: true

1. Provision. provision_twins mounts 1–6 catalog twins (ids from get_twin_catalog) and answers with routing: per-service mcp_url / rest_base_url, the world-level MCP, sessions_url for isolated forks, and an mcp_config block the agent can paste into the app under test. Seed it with scenario_id (a saved twsc_ scenario or a twsp_ preset) or scenario_prompt.
2. Drive. Either point the application at the routing URLs, or call run_model_on_twin: the model runs in a fresh isolated session and the record names every tool call, the final answer, and credential_source— the server’s key or the provider key saved under your account. Keys never travel through a tool argument.
3. Verify, keep, tear down. check_twin_health is a real probe (expect 15–20 s on production; read ok and checks[]). save_scenario_from_twin captures the rows added beyond the baseline as a reusable scenario. teardown_twin_environment delists the environment — the backing world is persistent data and is never destroyed.

Raw JSON-RPC with curl

# initialize — no key
$ curl -sS -X POST https://blobfish.ai/api/v1/twin/mcp \
    -H "Content-Type: application/json" -H "Accept: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

# tools/list — no key
$ curl -sS -X POST https://blobfish.ai/api/v1/twin/mcp \
    -H "Content-Type: application/json" -H "Accept: application/json" \
    -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# the catalog — no key
$ curl -sS -X POST https://blobfish.ai/api/v1/twin/mcp \
    -H "Content-Type: application/json" -H "Accept: application/json" \
    -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_twin_catalog","arguments":{}}}'

# provision — bf_ key required (without it: JSON-RPC error -32001, HTTP 401)
$ curl -sS -X POST https://blobfish.ai/api/v1/twin/mcp \
    -H "X-API-Key: $BLOBFISH_API_KEY" -H "Content-Type: application/json" -H "Accept: application/json" \
    -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"provision_twins","arguments":{"twins":["trolley"],"ttl_minutes":10}}}'

A tool result is {content: [{type: "text", text: <JSON>}], structuredContent, isError}. Notifications (no id) are acknowledged with 202; GET on the URL returns the discovery document.

Auth, planes, and errors

• initialize, ping, tools/list, and get_twin_catalog serve without a key. Every other tools/call needs a resolved identity; without one the server answers JSON-RPC error -32001 (HTTP 401) naming the x-api-key header and blobfish login.
• What a REST route refuses as 4xx comes back as a tool result with isError: true whose text is the same {error, detail} JSON plus http_status — e.g. twin_service_unavailable, invalid_ttl, invalid_twin_environment, environment_not_found, invalid_run_request, model_unavailable. Arguments are validated before any call: an unknown twin, a bad TTL, or a bad env_id never reaches the runtime.
• Website plane only. The cluster plane (tenv_ projections) is not operational on this deployment and is neither advertised nor accepted; a tenv_ id is refused with invalid_twin_environment. Expiry returns 410 from world surfaces until the lease is extended; teardown permanently revokes serving. Neither lifecycle action deletes retained world data.
• The same identity, the same records: environments and scenarios created here appear in the console, in blobfish twin-runs list, and on the REST API.

Next

Gateway & health · Models · Custom scenarios · Twin reference