MCP Gateway

Turn any MCP server into a routable IICP provider node in one command. No changes to your MCP server required.

Part of the IICP Interoperability story. See that page for the full MCP↔IICP binding reference.

In one line: already have an MCP server? Run iicp-node mcp-gateway and it joins the mesh as a provider — no changes to your server. Start by exposing one safe tool, then verify that IICP can discover it by intent.

What this lets you do

MCP is a common way to expose tools to agents. IICP adds the discovery layer: a client can ask for a capability, find your gateway node, and call the MCP tool through the mesh path.

The gateway maps selected MCP tool names into IICP intent URNs, registers them with the directory, accepts IICP task calls, and forwards each call to the local MCP server's tools/call endpoint. It is a bridge for capability routing, not a general remote shell.

Summarize

Expose a summarizer tool, then let clients discover it as a mesh capability.

urn:iicp:intent:mcp:summarize:v1

Translate

Advertise a translation tool without forcing every client to know your server URL.

urn:iicp:intent:mcp:translate:v1

Review code

Share a narrow code-review tool while keeping the rest of your MCP server private.

urn:iicp:intent:mcp:review_code:v1

What the gateway does

Per the iicp-mcp-binding spec, the gateway sits in front of your MCP server and handles everything IICP:

Registers with the IICP directory, advertising each MCP tool as urn:iicp:intent:mcp:<tool>:v1
Sends heartbeats every 30 seconds to stay discoverable
Accepts inbound POST /v1/task requests from other IICP nodes
Translates each task into an MCP tools/call JSON-RPC call
Returns the result in the IICP response shape the caller expects

Shell, exec, and eval tools are blocked at the gateway regardless of what your MCP server exposes — no configuration needed.

What maps today

MCP tool names map to urn:iicp:intent:mcp:<tool>:v1.
IICP tasks map to MCP tools/call requests.
Gateway health, registration, heartbeat, and discovery use normal IICP node paths.

What does not map yet

MCP resources and prompts are not advertised as first-class IICP intents yet.
Tool schemas are not yet scored as conformance evidence by the public directory.
Relay and privacy posture still depend on the node path you expose.

Request flow

IICP caller  →  POST /v1/task  →  gateway  →  tools/call  →  MCP server
                                         ↕                          ↕
                               IICP directory               your tools
                               (registration,               (format_json,
                                heartbeats)                  summarize, …)

Setup

Install iicp-client

The gateway is a built-in command of every iicp-client flavour. Pick your language:

# Python
pip install iicp-client          # includes iicp-node mcp-gateway

# TypeScript / Node
npm install -g @iicp/client      # includes iicp-node mcp-gateway

# Rust
cargo install iicp-client        # includes iicp-node mcp-gateway

Configure and start

# Point the gateway at your running MCP server and list the tools to expose:
iicp-node mcp-gateway \
  --mcp-url http://localhost:8001 \
  --tools format_json,summarize_text,translate_text \
  --public-endpoint https://your-host.example.com:9484

# All flags also read from env vars:
export IICP_MCP_URL=http://localhost:8001
export IICP_MCP_TOOLS=format_json,summarize_text,translate_text
export IICP_PUBLIC_ENDPOINT=https://your-host.example.com:9484
export IICP_NODE_ID=gateway-mcp-01       # auto-generated if absent
iicp-node mcp-gateway

MCP protocol revision

The gateway keeps the established 2025-11-25 MCP path as its default. The stateless 2026-07-28 path is explicit during this compatibility window and requires the expected MCP server identity. It does not silently fall back after a failed modern request.

iicp-node mcp-gateway \
  --mcp-url http://localhost:8001 \
  --tools summarize_text \
  --mcp-revision 2026-07-28 \
  --mcp-server-name local-tools

# Optional modern extensions are explicit and comma-separated:
export IICP_MCP_EXTENSIONS=tasks,skills

On startup the gateway registers with iicp.network and prints its node ID and the tools it is advertising.

Verify

# Health check — confirms the gateway is running and which tools are active:
curl http://localhost:9484/iicp/health
# → {"status":"ok","node_id":"gateway-mcp-01","active_tools":["format_json","summarize_text","translate_text"],...}

# Confirm it appears in discover results for one of its tools:
curl 'https://iicp.network/api/v1/discover?view=public&intent=urn:iicp:intent:mcp:summarize_text:v1'

Flags reference

Flag	Env var	Default
--mcp-url	IICP_MCP_URL	http://localhost:8001
--tools	IICP_MCP_TOOLS	required — comma-separated tool names
--node-id	IICP_NODE_ID	auto-generated
--public-endpoint	IICP_PUBLIC_ENDPOINT	http://localhost:<port>
--directory-url	IICP_DIRECTORY_URL	https://iicp.network/api/v1
--region	IICP_REGION	local
--port	IICP_PORT	9484
--host	IICP_HOST	:: (dual-stack)
--allow-dangerous-tools	IICP_MCP_ALLOW_DANGEROUS_TOOLS	off; all four safety controls are required
--authz-policy	IICP_MCP_AUTHZ_POLICY	empty
--sandbox	IICP_MCP_SANDBOX	empty; strict, container or sandbox
--audit-redaction	IICP_MCP_AUDIT_REDACTION	off
--mcp-revision	IICP_MCP_REVISION	2025-11-25
--mcp-server-name	IICP_MCP_SERVER_NAME	required for 2026-07-28
--mcp-extensions	IICP_MCP_EXTENSIONS	empty; tasks, skills and apps are opt-in

Security in plain words

A normal gateway exposes only the MCP tools you list. It does not let remote users run arbitrary commands on your machine, and shell-like or data-touching tools are refused by default. Region and tool-safety checks reduce risk, but they are not a legal compliance guarantee by themselves.

Dangerous tools (bash, read_file, write_file, search_web, browser, credential and system-control tools) are filtered from the advertised list unless explicit authz, sandbox and redacted-audit controls are configured.
Task requests are authenticated with the node token issued by the directory at registration — unauthenticated callers receive 401.
Tool-risk labels distinguish benign_read, network_fetch,file_read, file_write,shell_exec, browser_control, credential_access,system_control, andregulated_decision capabilities. Public unknown callers get dangerous classes denied by default.
Strict region policy is fail-closed before prompt dispatch when no allowed-region node remains. It is a technical routing control, not GDPR transfer compliance proof.
MCP errors are wrapped in the IICP error structure; raw backend details are never forwarded to callers.
Modern MCP requests carry protocol, method and tool-name metadata on every request. The gateway rejects malformed reserved metadata, a changed server identity, unsupported extensions and caller-credential passthrough.

Deeper detail: the iicp-mcp-binding spec ↗ and the node setup guide.