feat(mport): an MCP server is a capability surface; its bytes come back addressable

MPort already turned an origin into coordinates by reading OpenAPI or a
manifest. An MCP server offers something better: tools that describe
themselves, with input schemas, written to be called. So one tool becomes one
coordinate and nothing else in MPort changes — mock, dry_run, live, SEC-Ω, rate
limits, circuit breakers, retries, envelopes and broadcast all still apply,
because an MCP call is an ordinary POST once the body is shaped right.

Streamable HTTP, both framings: a server may answer JSON-RPC as application/json
or as a text/event-stream carrying the same frame, and the session id it issues
must ride every later request. Tests run against a real server over real HTTP,
parameterised across both transports.

Bytes never enter the mesh. A tool that returns content hands back base64; that
becomes a stored blob behind the existing snapshot store and travels as a URL.
The mesh routes to content, it does not carry it — base64 in a broadcast would
put megabytes on every antenna tuned to the frequency to deliver one artifact.

And it is not an image feature. MCP's `resource` block carries arbitrary bytes
with a mime type — a render, a mesh, a wasm module, a video — so those are
decoded and stored on the same path, `resource_link` is carried as an address,
and both the extension and the served content-type come from stdlib mimetypes
instead of a hand-written list of picture formats. Anything meshable is
addressable; anything addressable can be reached from wherever you are.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XGo2kuduWZMmEZGwKVNryU

core/mcp_client.py

@@ -0,0 +1,306 @@
+"""
+core/mcp_client.py — an MCP server, read as a capability surface.
+
+MPort already turns an origin into coordinates: OpenAPI gives it paths, a
+manifest gives it ops. An MCP server gives it something better — a list of
+tools that describe themselves, with input schemas, written to be called.
+
+So the mapping is direct: one MCP tool becomes one coordinate. Nothing else in
+MPort changes. mock, dry_run, live, SEC-Ω, rate limits, circuit breakers,
+retries, envelopes and broadcast all still apply, because an MCP call is an
+ordinary POST once the body is shaped right.
+
+Transport is Streamable HTTP (2025-03-26): one endpoint, POST JSON-RPC, and the
+server answers with either application/json or a text/event-stream carrying the
+same JSON-RPC frame. Both are handled here so callers never see the difference.
+
+What this module deliberately does NOT do: put bytes in the mesh. A tool that
+returns an image hands back base64; that becomes a stored blob and a URL, and
+only the URL travels as a signal. The mesh routes to content, it does not carry it.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import re
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+import httpx
+
+PROTOCOL_VERSION = "2025-03-26"
+_ACCEPT = "application/json, text/event-stream"
+
+# An MCP tool name is already an identifier; keep it recognisable in the coord.
+_IDENT = re.compile(r"[^a-zA-Z0-9_]+")
+
+
+def _ident(text: str) -> str:
+    return _IDENT.sub("_", (text or "").strip()).strip("_").lower() or "tool"
+
+
+def _parse_sse(body: str) -> Optional[dict]:
+    """Pull the first JSON-RPC frame out of an event stream."""
+    for line in body.splitlines():
+        if line.startswith("data:"):
+            chunk = line[5:].strip()
+            if chunk and chunk != "[DONE]":
+                try:
+                    return json.loads(chunk)
+                except json.JSONDecodeError:
+                    continue
+    return None
+
+
+def parse_response(content_type: str, text: str) -> dict:
+    """One JSON-RPC frame, whichever transport the server chose."""
+    if "text/event-stream" in (content_type or ""):
+        frame = _parse_sse(text)
+        if frame is None:
+            raise ValueError("event stream carried no JSON-RPC frame")
+        return frame
+    return json.loads(text)
+
+
+def rpc_body(method: str, params: Optional[dict] = None, rpc_id: Any = 1) -> dict:
+    body: Dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+    if rpc_id is not None:
+        body["id"] = rpc_id
+    if params is not None:
+        body["params"] = params
+    return body
+
+
+def call_body(tool: str, arguments: Optional[dict]) -> dict:
+    """The body that invokes one tool. This is what MPort POSTs in live mode."""
+    return rpc_body("tools/call", {"name": tool, "arguments": arguments or {}})
+
+
+async def _post(client: httpx.AsyncClient, endpoint: str, body: dict,
+                headers: Dict[str, str]) -> Tuple[Optional[dict], httpx.Response]:
+    r = await client.post(endpoint, json=body, headers=headers)
+    if r.status_code >= 400:
+        return None, r
+    if not (r.text or "").strip():          # notifications answer 202, no body
+        return None, r
+    return parse_response(r.headers.get("content-type", ""), r.text), r
+
+
+async def discover(endpoint: str, headers: Optional[Dict[str, str]] = None,
+                   timeout: float = 20.0) -> Dict[str, Any]:
+    """Handshake, then ask the server what it can do.
+
+    Returns the server's own words: its name, its protocol version, and its
+    tools with their input schemas. Raises on a server that will not talk.
+    """
+    hdrs = {"Content-Type": "application/json", "Accept": _ACCEPT,
+            "MCP-Protocol-Version": PROTOCOL_VERSION}
+    hdrs.update(headers or {})
+
+    async with httpx.AsyncClient(follow_redirects=True, timeout=timeout) as client:
+        init, resp = await _post(client, endpoint, rpc_body("initialize", {
+            "protocolVersion": PROTOCOL_VERSION,
+            "capabilities": {},
+            "clientInfo": {"name": "signalmesh-mport", "version": "2.0"},
+        }), hdrs)
+        if init is None:
+            raise ValueError(f"initialize failed: HTTP {resp.status_code}: "
+                             f"{(resp.text or '')[:200]}")
+        if "error" in init:
+            raise ValueError(f"initialize rejected: {json.dumps(init['error'])[:200]}")
+
+        # The session id, when the server issues one, must ride every later
+        # request or the server treats us as a stranger and 404s the session.
+        session_id = resp.headers.get("mcp-session-id") or ""
+        if session_id:
+            hdrs["Mcp-Session-Id"] = session_id
+
+        await _post(client, endpoint, rpc_body("notifications/initialized", rpc_id=None), hdrs)
+
+        listed, resp = await _post(client, endpoint, rpc_body("tools/list", {}, 2), hdrs)
+        if listed is None or "error" in (listed or {}):
+            detail = json.dumps((listed or {}).get("error", {}))[:200] or f"HTTP {resp.status_code}"
+            raise ValueError(f"tools/list failed: {detail}")
+
+    info = (init.get("result") or {}).get("serverInfo") or {}
+    return {
+        "server":     info.get("name") or "",
+        "version":    info.get("version") or "",
+        "protocol":   (init.get("result") or {}).get("protocolVersion") or "",
+        "session_id": session_id,
+        "tools":      (listed.get("result") or {}).get("tools") or [],
+    }
+
+
+def coords_from_tools(slug: str, endpoint: str, tools: List[dict],
+                      session_id: str = "") -> List[dict]:
+    """One tool, one coordinate — carrying the tool's own schema, not a guess."""
+    out: List[dict] = []
+    for t in tools:
+        if not isinstance(t, dict) or not t.get("name"):
+            continue
+        name = str(t["name"])
+        schema = t.get("inputSchema") or {}
+        props = schema.get("properties") or {}
+        out.append({
+            "coord":         f"submesh.{slug}.{_ident(name)}"[:140],
+            "method":        "POST",
+            "url":           endpoint,
+            "summary":       (t.get("description") or "").strip().split("\n\n")[0][:300],
+            "params":        list(props),
+            "requires_body": True,
+            "protocol":      "mcp",
+            "tool":          name,
+            "input_schema":  schema,
+            "required":      list(schema.get("required") or []),
+            "session_id":    session_id,
+        })
+    return out
+
+
+def _decode(raw: str, mime: str, kind: str, uri: str,
+            store_blob: Optional[Callable[[bytes, str], str]]) -> Dict[str, Any]:
+    entry: Dict[str, Any] = {"mime": mime, "kind": kind}
+    if uri:
+        entry["uri"] = uri
+    try:
+        data = base64.b64decode(raw, validate=True)
+        entry["bytes"] = len(data)
+        if store_blob:
+            entry["url"] = store_blob(data, mime)
+        else:                               # no store: say so, don't inline megabytes
+            entry["url"] = ""
+            entry["note"] = "not stored — no blob store supplied"
+    except Exception as e:
+        entry["error"] = f"undecodable {kind} payload: {type(e).__name__}"
+    return entry
+
+
+def normalize(frame: dict, store_blob: Optional[Callable[[bytes, str], str]] = None
+              ) -> Dict[str, Any]:
+    """Turn a tools/call frame into something a signal can carry.
+
+    Text stays text. Bytes — of any kind — are written through `store_blob` and
+    come back as a URL. That is the whole rule, and it is not about pictures: a
+    render, a mesh, a wasm module, a sound, a PDF all arrive the same way, and
+    all become addressable the same way. Base64 in a broadcast would put
+    megabytes on every antenna tuned to the frequency to deliver one artifact.
+    """
+    if "error" in frame:
+        err = frame["error"] or {}
+        return {"ok": False, "error": err.get("message") or "mcp error",
+                "code": err.get("code"), "text": "", "artifacts": [], "blocks": 0}
+
+    result = frame.get("result") or {}
+    texts: List[str] = []
+    artifacts: List[Dict[str, Any]] = []
+    blocks = result.get("content") or []
+
+    for b in blocks:
+        if not isinstance(b, dict):
+            continue
+        kind = b.get("type")
+        if kind == "text":
+            texts.append(str(b.get("text") or ""))
+
+        elif kind in ("image", "audio"):
+            artifacts.append(_decode(b.get("data") or "",
+                                     b.get("mimeType") or "application/octet-stream",
+                                     kind, "", store_blob))
+
+        elif kind == "resource":
+            # The general case. `blob` is arbitrary bytes with a mime type —
+            # glb, wasm, mp4, a Blender frame. Dropping it would make this an
+            # image feature instead of a transport.
+            res = b.get("resource") or {}
+            if res.get("blob"):
+                artifacts.append(_decode(res["blob"],
+                                         res.get("mimeType") or "application/octet-stream",
+                                         "resource", str(res.get("uri") or ""), store_blob))
+            elif res.get("text"):
+                texts.append(str(res["text"]))
+            elif res.get("uri"):
+                texts.append(str(res["uri"]))
+
+        elif kind == "resource_link":
+            # Already addressable at the origin; carry the address, fetch nothing.
+            artifacts.append({"kind": "link", "url": str(b.get("uri") or ""),
+                              "mime": b.get("mimeType") or "",
+                              "name": b.get("name") or ""})
+
+    return {
+        "ok":         not result.get("isError", False),
+        "text":       "\n".join(t for t in texts if t).strip(),
+        "artifacts":  artifacts,
+        "structured": result.get("structuredContent"),
+        "blocks":     len(blocks),
+    }
+
+
+if __name__ == "__main__":
+    png = base64.b64encode(b"\x89PNG\r\n\x1a\nFAKE").decode()
+
+    assert parse_response("text/event-stream",
+                          'event: message\ndata: {"jsonrpc":"2.0","id":1,"result":{}}\n\n'
+                          )["id"] == 1
+    assert parse_response("application/json", '{"jsonrpc":"2.0","id":2,"result":{}}')["id"] == 2
+
+    assert call_body("goto", {"url": "https://x"}) == {
+        "jsonrpc": "2.0", "method": "tools/call", "id": 1,
+        "params": {"name": "goto", "arguments": {"url": "https://x"}}}
+    assert "id" not in rpc_body("notifications/initialized", rpc_id=None)
+
+    coords = coords_from_tools("panda", "https://h/mcp", [
+        {"name": "screenshot", "description": "Grab the page.\n\nMore prose.",
+         "inputSchema": {"type": "object", "properties": {"url": {}, "full": {}},
+                         "required": ["url"]}},
+        {"no_name": True},
+    ])
+    assert len(coords) == 1, coords
+    c = coords[0]
+    assert c["coord"] == "submesh.panda.screenshot" and c["tool"] == "screenshot"
+    assert c["params"] == ["url", "full"] and c["required"] == ["url"]
+    assert c["summary"] == "Grab the page." and c["protocol"] == "mcp"
+
+    kept: List[Tuple[bytes, str]] = []
+    def _store(data: bytes, mime: str) -> str:
+        kept.append((data, mime))
+        return f"/blob/{len(kept)}"
+
+    out = normalize({"result": {"content": [
+        {"type": "text", "text": "here it is"},
+        {"type": "image", "data": png, "mimeType": "image/png"},
+        {"type": "resource", "resource": {"uri": "https://x/y.png"}},
+    ]}}, _store)
+    assert out["ok"] and out["blocks"] == 3
+    assert out["text"] == "here it is\nhttps://x/y.png", out["text"]
+    assert out["artifacts"] == [{"mime": "image/png", "kind": "image",
+                                 "bytes": 12, "url": "/blob/1"}], out["artifacts"]
+    assert kept[0][0].startswith(b"\x89PNG"), "stored bytes are the decoded image"
+
+    # base64 must never survive into the envelope — that is what the store is for
+    assert png not in json.dumps(out)
+
+    # bytes are bytes: a glb resource must survive exactly like a png did
+    glb = base64.b64encode(b"glTF\x02\x00\x00\x00mesh").decode()
+    out = normalize({"result": {"content": [
+        {"type": "resource", "resource": {"uri": "file:///scene.glb", "blob": glb,
+                                          "mimeType": "model/gltf-binary"}},
+        {"type": "resource_link", "uri": "https://x/live.webm",
+         "mimeType": "video/webm", "name": "viewport"},
+    ]}}, _store)
+    assert out["artifacts"][0] == {"mime": "model/gltf-binary", "kind": "resource",
+                                   "uri": "file:///scene.glb", "bytes": 12,
+                                   "url": "/blob/2"}, out["artifacts"][0]
+    assert kept[1][0].startswith(b"glTF"), "a 3D scene round-trips like any other bytes"
+    assert out["artifacts"][1] == {"kind": "link", "url": "https://x/live.webm",
+                                   "mime": "video/webm", "name": "viewport"}
+    assert glb not in json.dumps(out)
+
+    assert normalize({"result": {"content": [
+        {"type": "image", "data": "!!not base64!!", "mimeType": "image/png"}]}}, _store
+        )["artifacts"][0]["error"].startswith("undecodable")
+
+    err = normalize({"error": {"code": -32602, "message": "no such tool"}})
+    assert err["ok"] is False and err["code"] == -32602
+
+    print("mcp_client self-check OK")

core/submesh.py

@@ -55,6 +55,7 @@ from __future__ import annotations
 import asyncio
 import hashlib
 import json
+import mimetypes
 import os
 import queue
 import random
@@ -71,6 +72,7 @@ from fastapi.responses import HTMLResponse, StreamingResponse
 from pydantic import BaseModel, Field
 from core.source_hydrator import is_fetchable
 from core import dbmesh
+from core import mcp_client
 
 # ── Nicoli static harness catalog (bundled from cli-anything upstream) ────────
 try:
@@ -96,7 +98,7 @@ _PROMOTION_TTL_S  = 15 * 60   # dry_run promotions expire in 15 min
 
 class WrapReq(BaseModel):
     origin: str
-    kind: str = "url"                 # "url" | "manifest" | "nicoli" (Phase 1)
+    kind: str = "url"                 # "url" | "manifest" | "nicoli" | "mcp"
     cookies: Any = None
     headers: Any = None
     manifest: Optional[dict] = None
@@ -1634,7 +1636,58 @@ def _guess_ct(path: str) -> str:
                     (".woff2", "font/woff2"), (".woff", "font/woff"), (".ttf", "font/ttf")):
         if p.endswith(ext):
             return ct
-    return "application/octet-stream"
+    # Anything else addressable — glb, wasm, webm, mp4, stl — rather than
+    # handing every unlisted type back as a download.
+    for mime, extension in _MCP_MIME_EXT.items():
+        if p.endswith("." + extension):
+            return mime
+    guess, _ = mimetypes.guess_type(p)
+    return guess or "application/octet-stream"
+
+
+# Only what stdlib mimetypes does not already know. Everything else — png, svg,
+# wav, mp4, pdf, json — it maps for us, and it is not an image-only list.
+_MCP_MIME_EXT = {"model/gltf-binary": "glb", "model/gltf+json": "gltf",
+                 "model/stl": "stl", "model/obj": "obj",
+                 "application/wasm": "wasm", "video/webm": "webm",
+                 "image/webp": "webp", "application/x-blender": "blend"}
+
+
+def _mcp_ext(mime: str) -> str:
+    known = _MCP_MIME_EXT.get((mime or "").lower())
+    if known:
+        return known
+    guess = mimetypes.guess_extension((mime or "").split(";")[0].strip() or "")
+    return guess.lstrip(".") if guess else "bin"
+
+
+_MCP_BLOBS_PER_SLUG = 64
+
+
+def _store_mcp_blob(data: bytes, mime: str, slug: str) -> str:
+    """An MCP tool handed back bytes. Park them, hand back a URL.
+
+    Reuses the snapshot bundle store: it is already a TTL'd, capped,
+    content-typed blob store with a keyless read route in front of it, which is
+    exactly what an image needs to be viewable from an antenna or a chat bubble.
+    The mesh gets this URL; it never gets the bytes.
+
+    One bundle per origin, not one per image — _SNAPSHOT_MAX counts bundles, and
+    a token per picture would evict a site capture after four screenshots.
+    """
+    target = f"mcp:{slug}"
+    name = f"{uuid.uuid4().hex[:8]}.{_mcp_ext(mime)}"
+    token = next((t for t, s in _SNAPSHOTS.items() if s.get("target") == target), "")
+    if token:
+        files = _SNAPSHOTS[token]["files"]
+        # insertion order, not sorted() — the names are random, the order is not
+        for old in list(files)[:max(0, len(files) + 1 - _MCP_BLOBS_PER_SLUG)]:
+            files.pop(old, None)
+        files[name] = data
+        _SNAPSHOTS[token]["created"] = time.time()      # keep a live origin alive
+    else:
+        token = _store_snapshot({name: data}, host=slug, target=target)
+    return f"/api/submesh/preview/{token}/{name}"
 
 
 def _bundle_pages(files: dict):
@@ -3374,7 +3427,25 @@ def make_router(*, check_key, signal_registry, sec_omega, socket_limit=None) ->
 
         ops: List[dict] = []
         source = "default"
-        if req.manifest:
+
+        # ── kind="mcp": the server describes its own callable surface ───
+        # No guessing from paths — tools/list is the manifest, written by the
+        # people who built the thing. One tool becomes one coordinate.
+        if req.kind == "mcp":
+            try:
+                found = await mcp_client.discover(
+                    origin, {h["name"]: h["value"] for h in _normalize_headers(req.headers)})
+            except Exception as e:
+                raise HTTPException(502, f"MCP handshake failed at {origin}: "
+                                         f"{type(e).__name__}: {str(e)[:200]}")
+            ops = mcp_client.coords_from_tools(slug, origin, found["tools"],
+                                               found.get("session_id", ""))
+            if not ops:
+                raise HTTPException(422, f"{origin} answered tools/list with no tools — "
+                                         "nothing to register.")
+            base, source = origin, "mcp"
+
+        if not ops and req.manifest:
             ops = _coords_from_manifest(slug, base, req.manifest)
             source = "manifest"
         if not ops and req.kind == "url" and req.scan_openapi:
@@ -3879,13 +3950,22 @@ def make_router(*, check_key, signal_registry, sec_omega, socket_limit=None) ->
                 _path_keys.add(k)
         params: dict = {}
         body: Optional[dict] = None
-        if method == "GET":
+        is_mcp = op.get("protocol") == "mcp"
+        if is_mcp:
+            # The caller names arguments; JSON-RPC framing is ours to add.
+            body = mcp_client.call_body(op["tool"], req.input or {})
+        elif method == "GET":
             params = {k: v for k, v in (req.input or {}).items()
                       if k not in _path_keys and not str(k).startswith("_")}
         else:
             body = req.input or None
 
         hdrs = {"User-Agent": "SignalMesh-Submesh/0"}
+        if is_mcp:
+            hdrs["Accept"] = "application/json, text/event-stream"
+            hdrs["MCP-Protocol-Version"] = mcp_client.PROTOCOL_VERSION
+            if op.get("session_id"):
+                hdrs["Mcp-Session-Id"] = op["session_id"]
         for h in headers:
             try:
                 hdrs[str(h["name"])] = str(h["value"])
@@ -3992,7 +4072,12 @@ def make_router(*, check_key, signal_registry, sec_omega, socket_limit=None) ->
                                              cookies=jar, headers=hdrs) as client:
                     r = await client.request(method, url, params=params, json=body)
                     ct = r.headers.get("content-type", "")
-                    if "application/json" in ct:
+                    if is_mcp and r.status_code < 400:
+                        payload_type = "mcp"
+                        payload = mcp_client.normalize(
+                            mcp_client.parse_response(ct, r.text),
+                            lambda data, mime: _store_mcp_blob(data, mime, slug))
+                    elif "application/json" in ct:
                         payload_type, payload = "json", r.json()
                     else:
                         payload_type, payload = "text", r.text[:20000]

tests/test_mcp_wrap.py

@@ -0,0 +1,261 @@
+"""Wrapping an MCP server: its tools become coordinates, and an image comes back.
+
+Runs against a real MCP server over real HTTP — a small one, started in-process,
+that speaks Streamable HTTP and hands back a genuine PNG. The point is the whole
+round trip, not a mocked httpx: handshake, tools/list, coordinate registration,
+tools/call, and an image that arrives as a fetchable URL rather than base64 in
+the mesh.
+"""
+import base64
+import json
+import socket
+import threading
+import time
+
+import pytest
+import uvicorn
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse, PlainTextResponse
+from fastapi.testclient import TestClient
+
+import signalmesh_api as api
+from core import submesh
+
+# A 1x1 red PNG — small, real, and decodable by anything that renders images.
+RED_DOT = base64.b64decode(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==")
+
+TOOLS = [
+    {"name": "fetch_page", "description": "Fetch a page as text.",
+     "inputSchema": {"type": "object", "properties": {"url": {"type": "string"}},
+                     "required": ["url"]}},
+    {"name": "grab_image", "description": "Return the image at a URL.",
+     "inputSchema": {"type": "object", "properties": {"url": {"type": "string"}},
+                     "required": ["url"]}},
+    {"name": "render_scene", "description": "Return a 3D scene as a binary resource.",
+     "inputSchema": {"type": "object", "properties": {"name": {"type": "string"}}}},
+]
+
+# Not an image. The point is that the transport does not care.
+GLB = b"glTF\x02\x00\x00\x00" + b"\x00" * 40
+
+
+def _make_server(sse: bool = False) -> FastAPI:
+    """An MCP server. `sse=True` answers over text/event-stream instead of JSON."""
+    app = FastAPI()
+
+    def reply(frame: dict):
+        if sse:
+            return PlainTextResponse("event: message\ndata: " + json.dumps(frame) + "\n\n",
+                                     media_type="text/event-stream")
+        return JSONResponse(frame)
+
+    @app.post("/mcp")
+    async def mcp(request: Request):
+        body = await request.json()
+        method, rid = body.get("method"), body.get("id")
+
+        if method == "initialize":
+            r = JSONResponse({"jsonrpc": "2.0", "id": rid, "result": {
+                "protocolVersion": "2025-03-26", "capabilities": {"tools": {}},
+                "serverInfo": {"name": "test-panda", "version": "0.1"}}})
+            r.headers["Mcp-Session-Id"] = "sess-abc"
+            return r
+
+        if method == "notifications/initialized":
+            return PlainTextResponse("", status_code=202)
+
+        # Every post-handshake request must carry the session the server issued.
+        if request.headers.get("mcp-session-id") != "sess-abc":
+            return JSONResponse({"jsonrpc": "2.0", "id": rid, "error": {
+                "code": -32000, "message": "missing session"}}, status_code=400)
+
+        if method == "tools/list":
+            return reply({"jsonrpc": "2.0", "id": rid, "result": {"tools": TOOLS}})
+
+        if method == "tools/call":
+            p = body.get("params") or {}
+            name, args = p.get("name"), p.get("arguments") or {}
+            if name == "grab_image":
+                return reply({"jsonrpc": "2.0", "id": rid, "result": {"content": [
+                    {"type": "text", "text": f"image from {args.get('url')}"},
+                    {"type": "image",
+                     "data": base64.b64encode(RED_DOT).decode(),
+                     "mimeType": "image/png"}]}})
+            if name == "render_scene":
+                return reply({"jsonrpc": "2.0", "id": rid, "result": {"content": [
+                    {"type": "resource", "resource": {
+                        "uri": f"file:///{args.get('name', 'scene')}.glb",
+                        "mimeType": "model/gltf-binary",
+                        "blob": base64.b64encode(GLB).decode()}}]}})
+            if name == "fetch_page":
+                return reply({"jsonrpc": "2.0", "id": rid, "result": {"content": [
+                    {"type": "text", "text": f"contents of {args.get('url')}"}]}})
+            return reply({"jsonrpc": "2.0", "id": rid, "error": {
+                "code": -32602, "message": f"no such tool: {name}"}})
+
+        return reply({"jsonrpc": "2.0", "id": rid, "error": {
+            "code": -32601, "message": method}})
+
+    return app
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+@pytest.fixture(scope="module", params=[False, True], ids=["json", "sse"])
+def mcp_url(request):
+    port = _free_port()
+    server = uvicorn.Server(uvicorn.Config(_make_server(request.param),
+                                           host="127.0.0.1", port=port,
+                                           log_level="critical"))
+    threading.Thread(target=server.run, daemon=True).start()
+    for _ in range(100):
+        if server.started:
+            break
+        time.sleep(0.05)
+    assert server.started, "test MCP server did not start"
+    yield f"http://127.0.0.1:{port}/mcp"
+    server.should_exit = True
+
+
+@pytest.fixture
+def client(monkeypatch):
+    """MPort routes are managed — wrapping an origin changes the registry.
+
+    The test MCP server is on loopback, which MPort refuses by default so a
+    keyless caller cannot aim it at private infrastructure. A self-hoster opts
+    in with the same flag; see test_private_mcp_origin_is_refused_by_default.
+    """
+    monkeypatch.setenv("SIGNALMESH_ALLOW_PRIVATE_SOURCES", "1")
+    api._PAID_KEYS.add("test-paid-key")
+    try:
+        yield TestClient(api.app, headers={"X-SignalMesh-Key": "test-paid-key"})
+    finally:
+        api._PAID_KEYS.discard("test-paid-key")
+
+
+def test_tools_become_coordinates(client, mcp_url):
+    d = client.post("/api/submesh/wrap",
+                    json={"origin": mcp_url, "kind": "mcp"}).json()
+    assert d["source"] == "mcp", d
+    coords = [c["coord"] if isinstance(c, dict) else c for c in d["coords"]]
+    assert any(c.endswith(".grab_image") for c in coords), coords
+    assert any(c.endswith(".fetch_page") for c in coords), coords
+
+    op = next(o for o in submesh._COORDS.values()
+              if o["op"].get("tool") == "grab_image")["op"]
+    assert op["protocol"] == "mcp" and op["required"] == ["url"]
+    assert op["summary"] == "Return the image at a URL."
+
+
+def test_live_call_brings_an_image_back_as_a_url(client, mcp_url):
+    d = client.post("/api/submesh/wrap",
+                    json={"origin": mcp_url, "kind": "mcp"}).json()
+    coord = next(c["coord"] if isinstance(c, dict) else c
+                 for c in d["coords"] if str(c).endswith(".grab_image"))
+
+    env = client.post("/api/submesh/call", json={
+        "coord": coord, "input": {"url": "https://example.com/red.png"},
+        "mode": "live"}).json()
+
+    assert env["status"] == 200, env
+    assert env["payload_type"] == "mcp"
+    payload = env["payload"]
+    assert payload["ok"] and payload["text"].startswith("image from")
+
+    img = payload["artifacts"][0]
+    assert img["mime"] == "image/png" and img["bytes"] == len(RED_DOT)
+
+    # The bytes are reachable, and they are the bytes the tool sent.
+    got = client.get(img["url"])
+    assert got.status_code == 200, img["url"]
+    assert got.content == RED_DOT
+    assert got.headers["content-type"] == "image/png"
+
+
+def test_any_bytes_come_back_addressable_not_just_images(client, mcp_url):
+    """A 3D scene is not a picture, and nothing in the path should care.
+
+    MCP's `resource` block carries arbitrary bytes with a mime type — a render,
+    a mesh, a wasm module, a video. If only `image` blocks survived, this would
+    be an image feature instead of a transport.
+    """
+    d = client.post("/api/submesh/wrap",
+                    json={"origin": mcp_url, "kind": "mcp"}).json()
+    coord = next(c["coord"] if isinstance(c, dict) else c
+                 for c in d["coords"] if str(c).endswith(".render_scene"))
+
+    env = client.post("/api/submesh/call", json={
+        "coord": coord, "input": {"name": "fireflies"}, "mode": "live"}).json()
+
+    art = env["payload"]["artifacts"][0]
+    assert art["mime"] == "model/gltf-binary" and art["bytes"] == len(GLB)
+    assert art["uri"] == "file:///fireflies.glb"
+    assert art["url"].endswith(".glb"), art["url"]
+
+    got = client.get(art["url"])
+    assert got.status_code == 200
+    assert got.content == GLB
+    # served as a scene, not as an anonymous download
+    assert got.headers["content-type"] == "model/gltf-binary"
+    assert base64.b64encode(GLB).decode() not in json.dumps(env)
+
+
+def test_base64_never_reaches_the_mesh(client, mcp_url):
+    """A signal routes to content; carrying it would put megabytes on every
+    antenna tuned to the frequency, to show one picture."""
+    d = client.post("/api/submesh/wrap",
+                    json={"origin": mcp_url, "kind": "mcp"}).json()
+    coord = next(c["coord"] if isinstance(c, dict) else c
+                 for c in d["coords"] if str(c).endswith(".grab_image"))
+
+    env = client.post("/api/submesh/call", json={
+        "coord": coord, "input": {"url": "https://example.com/red.png"},
+        "mode": "live"}).json()
+
+    encoded = base64.b64encode(RED_DOT).decode()
+    assert encoded not in json.dumps(env)
+
+    slug = env["origin_slug"]
+    signals = api.signal_registry.tune_in([f"submesh.call.{slug}"])
+    assert signals, "the call was never broadcast"
+    assert encoded not in json.dumps(signals, default=str)
+
+
+def test_tool_error_is_reported_not_swallowed(client, mcp_url):
+    d = client.post("/api/submesh/wrap",
+                    json={"origin": mcp_url, "kind": "mcp"}).json()
+    coord = next(c["coord"] if isinstance(c, dict) else c
+                 for c in d["coords"] if str(c).endswith(".fetch_page"))
+
+    # Point a registered coordinate at a tool the server does not have.
+    submesh._COORDS[coord]["op"]["tool"] = "not_a_tool"
+    env = client.post("/api/submesh/call", json={
+        "coord": coord, "input": {}, "mode": "live"}).json()
+    assert env["payload"]["ok"] is False
+    assert "no such tool" in env["payload"]["error"]
+
+
+def test_private_mcp_origin_is_refused_by_default(monkeypatch, mcp_url):
+    """Without the opt-in, an MCP origin on the private network is refused —
+    otherwise wrap becomes a way to reach infrastructure MPort should not see."""
+    monkeypatch.delenv("SIGNALMESH_ALLOW_PRIVATE_SOURCES", raising=False)
+    api._PAID_KEYS.add("test-paid-key")
+    try:
+        c = TestClient(api.app, headers={"X-SignalMesh-Key": "test-paid-key"})
+        r = c.post("/api/submesh/wrap", json={"origin": mcp_url, "kind": "mcp"})
+        assert r.status_code == 400
+        assert "public http(s)" in r.json()["detail"]
+    finally:
+        api._PAID_KEYS.discard("test-paid-key")
+
+
+def test_wrapping_a_non_mcp_origin_fails_loudly(client):
+    r = client.post("/api/submesh/wrap",
+                    json={"origin": "https://example.com/not-mcp", "kind": "mcp"})
+    assert r.status_code == 502
+    assert "MCP handshake failed" in r.json()["detail"]