Protocol Interoperability

Send a POST to the directory with your public endpoint and MCP tool list. The directory assigns a node_token — save it.

curl -X POST https://iicp.network/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "my-mcp-server",
    "region": "us-east",
    "endpoint": "https://my-server.example.com",
    "capabilities": [{
      "intent": "urn:iicp:intent:mcp:tools/call:v1",
      "models": ["mcp-bridge"],
      "max_tokens": 4096
    }],
    "limits": { "max_concurrent": 4, "tokens_per_min": 10000 }
  }'
# → 201 {"node_token": "...", "node_id": "my-mcp-server", ...}

Nodes not seen for 90 seconds are marked unavailable.

# Python (add to your server startup)
import httpx, asyncio, os

TOKEN = os.environ["IICP_NODE_TOKEN"]

async def heartbeat_loop():
    async with httpx.AsyncClient() as client:
        while True:
            await client.post(
                "https://iicp.network/api/v1/heartbeat",
                headers={"Authorization": f"Bearer {TOKEN}"},
                json={"node_id": "my-mcp-server", "status": "available"},
                timeout=5.0,
            )
            await asyncio.sleep(30)

IICP clients POST to POST /v1/task on your endpoint. Extract the MCP tool name from the intent URN, dispatch to your MCP server, and return the result.

# Minimal FastAPI bridge — add to your existing MCP server
from fastapi import FastAPI, Header, HTTPException
from pydantic import BaseModel
import httpx, re, os

app = FastAPI()
TOKEN = os.environ["IICP_NODE_TOKEN"]

class IicpTask(BaseModel):
    task_id: str
    intent: str          # "urn:iicp:intent:mcp:<tool>:v1"
    payload: dict        # {"tool_name": str, "arguments": dict}
    auth: dict           # {"node_token": str}

@app.post("/v1/task")
async def handle_task(task: IicpTask, authorization: str = Header(...)):
    if task.auth.get("node_token") != TOKEN:
        raise HTTPException(401)

    # Extract tool name from intent URN
    # urn:iicp:intent:mcp:<tool_name>:v1  →  <tool_name>
    tool_name = task.payload.get("tool_name") or re.search(
        r"urn:iicp:intent:mcp:(.+):v1", task.intent
    ).group(1)

    # Dispatch to your MCP server (JSON-RPC 2.0)
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "http://localhost:3000/mcp",   # your MCP server
            json={
                "jsonrpc": "2.0", "id": task.task_id,
                "method": "tools/call",
                "params": {"name": tool_name, "arguments": task.payload.get("arguments", {})},
            },
        )
    result = resp.json()

    if "error" in result:
        return {"status": "error", "error": {"code": "backend_error", "mcp_error": result["error"]}}
    return {"status": "success", "result": result["result"]}

@app.get("/iicp/health")
async def health():
    return {"status": "available", "node_id": "my-mcp-server"}

That's it. Your MCP server is now discoverable in the IICP mesh under urn:iicp:intent:mcp:tools/call:v1 — clients can find it via GET /api/v1/discover?view=public&intent=urn:iicp:intent:mcp:tools/call:v1.