eco-mcp-app

An inline Claude Desktop widget for the Eco via Sirens game server . Ask Claude "what's the Eco server doing?" and you get a live card back: meteor countdown, online/total players, plants and animals, world size, laws, economy, Discord CTA. No screenshots, no tab-switching.

It's also a tech demo — a minimal, hand-rolled MCP Apps implementation without a bundler or React, so the whole iframe is one 300-line HTML file. Useful as a reference for anyone else building an MCP App in Python rather than the default TypeScript/ext-apps stack.

What it renders

┌─ Eco via Sirens ─────────── Established · day 2 · HighCollaboration · Slow ─ ● online ─┐
│                                                                                       │
│  DAYS UNTIL METEOR ☄                                          ┌─────┐                  │
│  57 days                                                      │ 57  │  (cycle ring,   │
│  Server running for 2 days · 5% through the cycle             │ left│  fills as days  │
│                                                               └─────┘   tick down)    │
│                                                                                       │
│  ┌ Players online ┐ ┌ World       ┐ ┌ Cycle progress  ┐ ┌ Economy & culture ┐        │
│  │ 7 / 67         │ │ 0.52 km²    │ │ day 2           │ │ 473 trades,       │        │
│  │ peak 38        │ │ 96k plants  │ │ 57d until ☄     │ │   0 contracts     │        │
│  │ ░░░░█░░░░░░░░░ │ │ 0 animals   │ │ ██░░░░░░░░░░░░░ │ │ 171.0 culture     │        │
│  └────────────────┘ └─────────────┘ └─────────────────┘ └───────────────────┘        │
│                                                                                       │
│  [v 0.13.0.2] [English] [open] [admin online]         Fetched 4:12 PM · [Join Discord]│
└───────────────────────────────────────────────────────────────────────────────────────┘

          · · · .        ·     .                 . ·
     .        ·   .    *   .          ·   . (animated starfield, twinkling)
       *              .         *                 ·
                                                         ☄ (meteor, floats)
                                                       ↙
                                                     ↙

How it works

The server (src/eco_mcp_app/server.py) exposes one tool, get_eco_server_status, which hits http://eco.coilysiren.me:3001/info (the public /info endpoint Eco servers expose by default), redacts player names, and returns two content blocks: a markdown fallback for text-only hosts, and a JSON payload for the iframe. The tool's _meta.ui.resourceUri points at ui://eco/status.html, which is the iframe HTML registered as a resource.

The iframe (src/eco_mcp_app/ui/eco.html) is plain HTML/CSS/JS — no build step, no bundler, no React. It hand-rolls the MCP Apps initialization handshake per the spec :

1. Iframe → host: ui/initialize (request, with protocolVersion: 2026-01-26)

2. Host → iframe: initialize result

3. Iframe → host: ui/notifications/initialized (notification)

4. Host → iframe: ui/notifications/tool-result whenever a matching tool fires

The handshake is ~30 lines. The ext-apps SDK does more (auto-resize, capability negotiation), but for a read-only dashboard we don't need any of it — and writing it out makes the spec readable.

See also

This repo sits next to a small Eco ecosystem: eco-cycle-prep runs per-cycle setup (worldgen, Discord announcements, mod sync); eco-agent was an earlier FastAPI companion service for the same server; eco-mods-public is where the gameplay mods live. Server infrastructure is defined in infrastructure (k3s + pyinvoke + external-secrets + Traefik). Canonical Eco references: ModKit , modding docs , Eco wiki modding page , the Discord bridge plugin , and mod catalog .

Install (local, Claude Desktop)

Claude Desktop only loads MCPs at startup, so install + restart:

cd /Users/kai/projects/coilysiren/eco-mcp-app
uv sync
python scripts/install-desktop-config.py

Then fully quit Claude Desktop (⌘Q) and relaunch. In a fresh chat:

Use eco-mcp-app to show me the Eco server status.

You should get the meteor card inline.

Deploy (homelab)

The long-term target is eco-mcp.coilysiren.me on the same k3s cluster that already hosts eco-agent. Pattern is unchanged from infrastructure :

• Build a Docker image (Dockerfile TODO)

• Manifests in deploy/ (Deployment, Service, Ingress, TLS via cert-manager, ClusterIssuer already in the infra repo)

• No secrets needed — the /info endpoint is public; server runs without env vars

MCP-over-HTTP brings its own spec pitfalls (session-id splits and resource registration scoping, tracked upstream in ext-apps#481), so the initial deploy will likely be the same stdio binary wrapped as a Streamable-HTTP server via the mcp SDK's HTTP transport — that's a later cycle's problem.

Smoke test

The whole MCP → iframe → render flow is testable via stdio without Claude:

inv smoke

Look for: _meta.ui.resourceUri in both forms on id=2, a real-sized HTML resource on id=3, and a JSON payload with "view":"eco_status" on id=4.

Dev harness (iterate on the iframe without restarting Claude)

dev/harness.html is a minimal HTML page that mimics Claude Desktop's MCP Apps host so the iframe can be developed in a normal browser — no ⌘Q / relaunch cycle per change. The harness:

1. Loads src/eco_mcp_app/ui/eco.html as an iframe (visibility: hidden).

2. Listens for ui/initialize from the iframe and responds with a valid McpUiInitializeResult (protocolVersion, hostInfo, hostCapabilities, hostContext).

3. On ui/notifications/initialized, reveals the iframe.

4. Listens for ui/notifications/size-changed and applies the reported {width, height} to iframe.style.height. This is the mechanism Claude Desktop actually uses — not the documentElement.height read that claude-ai-mcp#69 describes.

5. After reveal, pushes a canned ui/notifications/tool-result with a mock Eco /info payload so render() runs.

Run it with:

inv harness
# then open http://localhost:8765/dev/harness.html

The status bar at the top of the harness shows the last size-changed value so you can see whether the iframe is telling the host to resize. If it says "Loading…" forever, either the handshake failed or the iframe's script threw before reaching connect() — check DevTools console.

The harness is also usable from Claude Code's Preview panel via the eco-harness entry in .claude/launch.json.

MCP Apps — non-obvious things I learned building this

• _meta.ui.resourceUri must be set in both nested (ui.resourceUri) and flat (ui/resourceUri) forms — some hosts only honor one .

• The MIME type has to be exactly text/html;profile=mcp-app; plain text/html does not trigger MCP Apps rendering.

• With no client-side JS running the handshake, Claude Desktop correctly leaves the iframe container at visibility: hidden. This means a no-script test HTML is not a valid isolation — it will look identical to a broken app .

• Claude Desktop's sandbox iframe enforces a hardcoded CSP that ignores _meta.ui.csp extensions . External image origins get blocked. If you need thumbnails, inline them server-side as data:image/...;base64,... URIs — those are always permitted.

• Only Claude Desktop chat UI (clientInfo.name = "claude-ai") advertises the io.modelcontextprotocol/ui extension capability. Claude Code Desktop's agent harness (clientInfo.name = "local-agent-mode-*") does not, so iframes never render there — use its Launch preview panel (triggered by a Write or Edit tool call on a local HTML file) as the fallback inline-visualization path.

License

MIT.

References

1. https://www.coilysiren.me/

2. https://modelcontextprotocol.io/docs/concepts/apps

3. https://github.com/modelcontextprotocol/ext-apps

4. https://play.eco/

5. https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx

6. https://github.com/coilysiren/eco-cycle-prep

7. https://github.com/coilysiren/eco-agent

8. https://github.com/coilysiren/eco-mods-public

9. https://github.com/coilysiren/infrastructure

10. https://github.com/StrangeLoopGames/EcoModKit

11. https://docs.play.eco/

12. https://wiki.play.eco/en/Modding

13. https://github.com/Eco-DiscordLink/EcoDiscordPlugin

14. https://mod.io/g/eco

15. https://github.com/anthropics/claude-ai-mcp/issues/71

16. https://github.com/anthropics/claude-ai-mcp/issues/61#issuecomment-4283640203

17. https://github.com/anthropics/claude-ai-mcp/issues/40