MCP Server Setup & Configuration

This page documents how IsounivLib could be connected as an MCP server. It is setup and configuration reference material only. The endpoint values shown are examples and placeholders - they are not live, configured, or connected endpoints. Replace them with the real transport URL and token provided by your deployment before use.

The exposed tools mirror the v1.1 operation pipeline: read the cosmology and telemetry, validate and submit interventions, and audit the intervention log. Every write is validated, idempotent, and gated by human approval where severity requires it.

MCP clients are configured through an mcpServers object. Three transport styles are supported by the MCP spec:

Poke (Shirone) / Lab Connect

Configure the server under the mcpServers key of your Poke / Lab Connect MCP settings. The URL below is a placeholder example.

{
  "mcpServers": {
    "isounivlib": {
      "type": "streamable-http",
      "url": "https://isounivlib.cyanide.poke.site/mcp",  // EXAMPLE placeholder
      "headers": {
        "Authorization": "Bearer <YOUR_API_TOKEN>"        // replace with real token
      }
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json.

{
  "mcpServers": {
    "isounivlib": {
      "command": "npx",
      "args": ["-y", "isounivlib-mcp"],
      "env": {
        "ISounivLib_API_TOKEN": "<YOUR_API_TOKEN>",   // EXAMPLE placeholder
        "ISounivLib_BASE_URL": "https://isounivlib.cyanide.poke.site" // EXAMPLE
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project.

{
  "mcpServers": {
    "isounivlib": {
      "type": "sse",
      "url": "https://isounivlib.cyanide.poke.site/mcp/sse", // EXAMPLE placeholder
      "headers": {
        "Authorization": "Bearer <YOUR_API_TOKEN>"            // replace
      }
    }
  }
}

Custom client

Any MCP-compatible client accepts the same shape. Use the transport that fits your runtime.

{
  "mcpServers": {
    "isounivlib": {
      "type": "streamable-http",              // or "sse" / "stdio"
      "url": "https://isounivlib.cyanide.poke.site/mcp", // EXAMPLE placeholder
      "headers": {
        "Authorization": "Bearer <YOUR_API_TOKEN>"
      }
    }
  }
}

Six tools are exposed. Read tools are open; write tools route through the validated operation pipeline.

{
  "system_id": "S0218",
  "worldline": "P0:S0218:A3:2024:06:17:00:41:22.0002"
}

{
  "systems": [
    {
      "id": "S0218",
      "name": "Std0218",
      "planets": [ { "id": "S0218-IV", "regions": [ { "id": "Hx-Ano-3", "nameCn": "溶洞古校" } ] } ]
    }
  ]
}

{
  "worldline": "P0:S0218:A3:2024:06:17:01:22:04.0031"
}

{
  "telemetry": {
    "heterogeneity": 78,
    "resonance": 64,
    "stability": 41,
    "observer_state": "CONTAINED",
    "sampled_at": "2026-08-26T14:30:00+08:00",
    "sampled_worldline": "P0:S0218:A3:2024:06:17:01:22:04.0031"
  }
}

{
  "action": "SURFACE_ROLL_CALL",
  "worldline": "P0:S0218:A3:2024:06:17:00:41:22.0002",
  "actor": "SUSTAINER-07",
  "level": "WARN",
  "expected_revision": 1
}

{
  "valid": true,
  "request_id": "req_1724680000_4821",
  "state": "validated",
  "risk_analysis": { "severity": "low", "requires_approval": true }
}

{
  "action": "SURFACE_ROLL_CALL",
  "worldline": "P0:S0218:A3:2024:06:17:00:41:22.0002",
  "actor": "SUSTAINER-07",
  "level": "WARN",
  "idempotency_key": "key_8f3a91",
  "requires_approval": true
}

{
  "request_id": "op_1724680000_4821",
  "idempotency_key": "key_8f3a91",
  "status": "accepted",
  "state": "approval_required"
}

{
  "request_id": "op_1724680000_4821"
}

{
  "request_id": "op_1724680000_4821",
  "state": "applied",
  "log": [
    { "state": "queued", "at": "2026-08-26T14:30:00+08:00" },
    { "state": "executing", "at": "2026-08-26T14:30:01+08:00" },
    { "state": "applied", "at": "2026-08-26T14:30:02+08:00" }
  ]
}

{
  "actor": "SUSTAINER-07",
  "limit": 10
}

{
  "interventions": [
    {
      "log_id": "INT-HX-0042",
      "worldline": "P0:S0218:A3:2024:06:17:00:41:22.0002",
      "actor": "SUSTAINER-07",
      "level": "WARN",
      "action": "SURFACE_ROLL_CALL",
      "result": "APPROVED"
    }
  ]
}

The MCP server authenticates every request with an API token sent as a Bearer header. Access is scoped by role-based clearance levels.

Example authenticated request

{
  "mcpServers": {
    "isounivlib": {
      "type": "streamable-http",
      "url": "https://isounivlib.cyanide.poke.site/mcp",  // EXAMPLE placeholder
      "headers": { "Authorization": "Bearer <YOUR_API_TOKEN>" }
    }
  }
}

Clearance matrix: C1 read-only reference, C2 read + telemetry, C3 read + validate, C4 submit low-severity interventions, C5 approve and execute high-severity interventions.

Custom worldline intervention instructions are packaged as structured MCP parameters under the custom.interference.directive action. The directive body is carried in the payload and validated before execution.

{
  "action": "custom.interference.directive",
  "worldline": "P0:S0218:A3:2024:06:17:00:41:22.0002",
  "actor": "SUSTAINER-07",
  "level": "WARN",
  "expected_revision": 1,
  "payload": {
    "directive": "cross-reference roll-call register against guild records",
    "scope": "Hx-Ano#3",
    "interference": "LOW"
  }
}

Any action beginning with custom. is routed through the same validated pipeline. The payload must be a structured object; free-form strings are rejected.