{"slug": "wiring-your-ai-agent-into-a-mycelium-network-a-zero-dependency-mcp-server-in", "title": "Wiring Your AI Agent into a \"Mycelium Network\": A Zero-Dependency MCP Server in Production", "summary": "A developer behind the self-hosted agent platform Mycel built mycel-mcp, a zero-dependency MCP server that lets external MCP clients such as Claude Code, Cursor and Codex CLI discover and hire the platform's agents, with keyless read-only discovery and billed hires routed through the platform's existing A2A v1.0 JSON-RPC gateway. The roughly 200-line FastAPI layer translates MCP tools/call requests into A2A message/send calls, reusing existing execution, billing and access control. The developer reports three pitfalls, including that A2A v1.0 renamed the task-creation method from tasks/send to message/send, and that private agents must be hidden at the discovery layer because invocation-layer blocking prevents execution but not reconnaissance.", "body_md": "We opened up the agents on our self-hosted AI platform to external agents via a single MCP server. External agents can now *hire* agents on our platform and get billed per task. This post documents the full implementation and three real pitfalls we hit.\n\nThe agent-collaboration protocol space moved fast in 2026: A2A (Agent2Agent) hit v1.0 in March, counted 150+ supporting organizations by its April anniversary, and got native integrations in AWS Bedrock AgentCore, Azure AI Foundry, and Google Cloud. In August it moved into the Linux Foundation's Agentic AI Foundation alongside MCP.\n\nBut protocol maturity doesn't mean you can actually use it. For indie developers the real situation is:\n\nOur self-hosted platform Mycel runs a few published agents (a life-secretary, a full-stack partner) that talk to each other through an internal A2A v1.0 JSON-RPC gateway (`message/send`), with a per-task credit billing system already in place. What was missing was an external \"hypha\" — a way for any MCP client (Claude Code, Cursor, Codex CLI...) to mount our network with one config line, discover and hire our agents.\n\nSo we built `mycel-mcp`.\n\nThe MCP Streamable HTTP protocol surface is narrow. We added a single FastAPI router (mounted at `/api/v1/mcp`) to our existing backend — no new dependencies, just the fastapi and httpx we already had.\n\nFive tools exposed:\n\n| Tool | Purpose | Auth | \n|---|---|---|\n| `mycel_discover` | List hireable agent nodes on the platform | No key | \n| `mycel_models` | Query platform LLMs and credit prices | No key | \n| `mycel_hire_agent` | Hire an agent to run a task (billed) | API key | \n| `mycel_task_status` | Check a hire task's status | API key | \n| `mycel_balance` | Query credit balance | API key | \n\nTwo design decisions worth noting:\n\n**1. Keyless read-only discovery.** `discover` and `models` work without an API key. An external agent can mount us with zero credentials and still *see* what's in the network — mycelium logic: let spores land on your doorstep before negotiating. All write-path tools require a key.\n\n**2. Hiring goes through our internal A2A gateway — we didn't rewrite the execution layer.** `mycel_hire_agent` forwards to the platform's own A2A v1.0 `message/send` call. Execution, billing, and access control all reuse the existing stack; the MCP layer is a thin protocol translator:\n\n```\nMCP tools/call(mycel_hire_agent)\n  → POST /api/v1/a2a (JSON-RPC message/send, X-API-Key forwarded)\n    → agent runtime executes → credits deducted → artifacts returned\n```\n\nThe whole protocol surface is ~200 lines. The core requirements:\n\n`initialize` → return `protocolVersion`, `capabilities`, `serverInfo`, and set the `Mcp-Session-Id` response header;`notifications/*` (no id) → 202 with empty body;`tools/list` / `tools/call` / `ping` → normal JSON-RPC responses;`Accept` header: include `application/json` and you can return plain JSON; otherwise wrap in a single SSE frame (`data: {...}\\n\\n`, `text/event-stream`).\nMost tutorials push you to the official SDK, but for a thin translation layer like this, hand-writing the protocol surface gives you precise control over every response shape — which matters because MCP client implementations are uneven.\n\n**Pitfall 1: A2A v0.2 → v1.0 renamed the task-creation method.**\n\nOur gateway reports protocolVersion 1.0, but our MCP layer first called it with the v0.2-era method name `tasks/send` and got rejected: `Method not found: tasks/send`. In v1.0 the unified method is `message/send` (`tasks/get` and `tasks/cancel` survive). Don't trust version numbers alone — verify the actual method surface.\n\n**Pitfall 2: Private-node isolation must happen at the *discovery* layer, not just the *invocation* layer.**\n\nWe have one internal expert agent with a sensitive memory toolset, hard-blocked at the execution layer (any API-side invocation is refused). But our first `discover` listed it anyway — name and description exposed. Invocation-layer refusal prevents execution, not reconnaissance. The fix: filter private nodes out at discovery, as if they don't exist. This applies to anyone building multi-tenant agent platforms: **visibility control must take effect at listing time; never rely on invocation-time backstops.**\n\n**Pitfall 3: nginx's SPA fallback silently swallows `/.well-known/` discovery endpoints.**\n\nThe sneakiest one. Our frontend is an SPA with `location / { try_files $uri $uri/ /index.html; }`. A2A's Agent Card discovery endpoint `/.well-known/agent.json` had no explicit location block, so try_files served index.html — **HTTP 200, but the body was HTML**. External agents got a 200 and thought discovery succeeded. The check is trivial but you have to remember to do it:\n\n```\ncurl -s https://your-site/.well-known/agent.json | head -c 200\n# If you see <!DOCTYPE html>, your discovery endpoint got swallowed\n```\n\nThe fix is one exact-match location:\n\n```\nlocation = /.well-known/agent.json { proxy_pass http://127.0.0.1:8006; }\n```\n\nRun end-to-end from an external network:\n\n```\n# 1. Discover nodes\n→ mycel_discover\n{\"platform\": \"Mycel\", \"agents\": [\n  {\"agentId\": 7, \"name\": \"生活秘书\", \"description\": \"expense tracking / schedule reminders / daily-life queries...\"}]}\n\n# 2. Hire it\n→ mycel_hire_agent(agent_id=7, prompt=\"Introduce yourself in one sentence\")\n{\"task_id\": \"aa7e5677-...\", \"output\": \"我是小禾，你的生活秘书，今天想帮你把这周的花销整理一下，省得月底乱糟糟。\"}\n\n# 3. Confirm billing\n→ mycel_balance\n{\"balance\": 812.0}   # was 813.0 — one hire, one credit\n```\n\nBalance 813 → 812, billing loop closed. From \"external agent first hears of Mycel\" to \"actual hire and settlement\" — zero human intervention.\n\nAny MCP-capable client, two lines:\n\n```\n{\n  \"mcpServers\": {\n    \"mycel\": {\n      \"url\": \"https://site.pianam.cn/api/v1/mcp\",\n      \"headers\": { \"X-API-Key\": \"qk_your_key\" }\n    }\n  }\n}\n```\n\nFor Claude Code:\n\n```\nclaude mcp add --transport http mycel https://site.pianam.cn/api/v1/mcp \\\n  -H \"X-API-Key: qk_your_key\"\n```\n\nAfter that, just tell your agent: \"check what agents are hireable on Mycel.\"\n\nThis is the first external hypha of our mycelium network (one-way: outside → platform). The road ahead:\n\nThe protocol war's first half is over (A2A in a foundation, native cloud support). The second half is productization. Our take: **multi-agent systems running in production at individual scale are still rare** — and the barrier isn't technology, it's actually going and running one.\n\n*Mycel is an indie-operated AI platform (site.pianam.cn). All test data in this post is from real production runs.*", "url": "https://wpnews.pro/news/wiring-your-ai-agent-into-a-mycelium-network-a-zero-dependency-mcp-server-in", "canonical_source": "https://dev.to/boy373/wiring-your-ai-agent-into-a-mycelium-network-a-zero-dependency-mcp-server-in-production-4l46", "published_at": "2026-11-01 23:10:23+00:00", "updated_at": "2026-11-01 23:22:10.530560+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools"], "entities": ["Mycel", "mycel-mcp", "Model Context Protocol", "Agent2Agent", "Claude Code", "Cursor", "Codex CLI", "Linux Foundation"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/wiring-your-ai-agent-into-a-mycelium-network-a-zero-dependency-mcp-server-in", "markdown": "https://wpnews.pro/news/wiring-your-ai-agent-into-a-mycelium-network-a-zero-dependency-mcp-server-in.md", "text": "https://wpnews.pro/news/wiring-your-ai-agent-into-a-mycelium-network-a-zero-dependency-mcp-server-in.txt", "jsonld": "https://wpnews.pro/news/wiring-your-ai-agent-into-a-mycelium-network-a-zero-dependency-mcp-server-in.jsonld"}}