SH0.DEV MCP: When Your AI Has 30 Tools But Can Only See 15

A user opened the sh0 dashboard, asked the AI to deploy Redis, and got back: "I don't have a tool to create new apps. Please use the CLI or the dashboard UI."

The AI was wrong. The tool existed. It had been implemented, tested, and deployed. The MCP server registered it correctly. But the AI could not see it.

This is the story of a bug that lived in the gap between two systems, how we found it, and the architectural decision that killed an entire class of future bugs.

The Bug Report

Two bugs arrived on the same day, from the same root cause:

Bug 1: The AI sandbox feature was enabled on a container. The sandbox container was running (we could see the Docker ID in server logs). But the AI had no sandbox tools. Zero. It could not run a single command in the container sitting right next to it.

Bug 2: The AI could not create new apps. It had deploy_app (which redeploys an existing app), but no create_app, no deploy_template, no deploy_compose. Asking "deploy nginx:latest" returned an error because it tried to redeploy a non-existent app.

Both bugs shared a devastating punchline: the tools existed. The MCP server had 30 tools. The AI could only see 15.

The Architecture That Created the Gap

sh0's AI system has a three-layer architecture:

Dashboard (Svelte 5 SPA)
    |
    | source: 'dashboard'
    v
Gateway (sh0.dev/api/ai/chat)
    |
    | MCP or Legacy?
    v
sh0 Server (MCP at :9000/mcp)

When the gateway receives a request, it picks one of three paths:

MCP mode: Claude connects directly to the sh0 MCP server. All 30 tools available.
Legacy mode: Claude gets a hardcoded CLIENT_TOOLS array. 15 tools.
Docs mode: No server access. Documentation search only.

The choice depends on one thing: does the gateway have a verified MCP connection for this user?

The dashboard always sent source: 'dashboard' but never sent MCP connection info. No MCP config existed in the database. Every single dashboard request went through legacy mode.

The CLIENT_TOOLS array was written months ago when the AI had 12 tools. The MCP server grew to 30 over five phases of development. Nobody updated the legacy array. The gap widened silently with every new MCP tool we shipped.

Why We Missed It

This is the insidious part. The MCP server had thorough tests:

test_manual_tool_definitions ... ok (25 tools verified)

The tools were registered. They responded to tools/list. They executed correctly when called via MCP. Every test passed.

But the tests tested the MCP server. The dashboard used the legacy path. The two systems were independently correct and collectively broken.

The server logs even showed the sandbox container starting:

INFO sh0: Global AI sandbox ready
    id=281b4a6c900a77ef...

The sandbox was alive. The MCP tool was registered. But the dashboard AI had no way to reach either. The bridge between them did not exist.

The Fix: MCP-First with Legacy Fallback

We could have just added the 15 missing tools to CLIENT_TOOLS and called it a day. That would fix the immediate bugs. But it would leave the same architectural flaw in place: two independently maintained tool registries that would drift apart again the next time someone added a tool to MCP.

Instead, we designed a three-part fix:

1. Dashboard Sends MCP Connection Info

The dashboard knows its own server URL. The sh0 server has an auth system that issues JWTs. We added a new endpoint (POST /auth/ai-session-token) that generates a short-lived JWT from the current session. The dashboard now sends:

typescriptbody.instance_url = window.location.origin;
body.instance_api_key = await getAiSessionToken();

The gateway's ad-hoc MCP code activates, Claude connects directly to the MCP server, and all 30 tools are available. No separate MCP configuration needed.

2. Expanded Legacy as Offline Fallback

MCP requires Anthropic's servers to reach the sh0 MCP endpoint. For localhost development, they cannot. So we expanded CLIENT_TOOLS to full parity with MCP: all 9 missing tools added.

For sandbox tools, the dashboard could not call Docker directly (it runs in the browser). We created 5 new REST endpoints that mirror the MCP sandbox logic:

POST /api/v1/sandbox/exec
POST /api/v1/sandbox/read-file
GET  /api/v1/sandbox/processes
POST /api/v1/sandbox/connectivity
GET  /api/v1/sandbox/status

Each endpoint replicates the exact logic from the MCP tool implementations -- same resolve_sandbox() function, same global vs. per-app routing, same Docker calls, same audit logging.

3. Fixed MCP Fallback (The Hidden Third Bug)

While investigating, we found another bug: when MCP mode fails (timeout, network error), the gateway fell back to docs mode -- which has zero server tools. Dashboard users went from "all tools" to "no tools" on any MCP hiccup.

typescript// Before: dashboard user loses all server tools
catch (mcpError) {
    await streamDocsPath(...);
}

// After: dashboard user keeps legacy tools
catch (mcpError) {
    if (isDashboard) {
        await streamLegacyPath(...);
    } else {
        await streamDocsPath(...);
    }
}

Five lines. One of those fixes that makes you wonder how many users silently hit this path and assumed the AI was just limited.

The Localhost Trap: Why MCP Cannot Work on Your Dev Machine

This is the section we wish someone had written for us. If you are building an MCP server and testing it locally, you will hit this wall.

MCP Connector mode does not work on localhost. This is not a bug. It is an architectural constraint that affects every developer building with Anthropic's MCP client.

Here is why. When you use Claude's MCP Connector (the mcp_servers parameter in the API), the flow looks like this:

Your App -> Anthropic API -> Claude -> MCP Server (your server)
                                          ^
                                          |
                                   Anthropic's servers
                                   must reach THIS URL

Claude does not run on your machine. It runs on Anthropic's infrastructure. When Claude needs to call an MCP tool, Anthropic's servers connect to the MCP URL you provided. If that URL is http://localhost:9000/mcp, Anthropic's servers try to connect to their own localhost. Your server is not there.

This is not a misconfiguration. This is how HTTP works. localhost means "this machine," and Anthropic's machine is not your machine.

What Developers Experience

You set up your MCP server. You test it with curl -- it works. You configure the MCP URL in your app. You send a message to Claude. Claude responds but never calls any tools. No error message. No warning. Just... silence where tool calls should be.

You check your server logs. No incoming connection. You wonder if your MCP implementation is wrong. You add more logging. You try different JSON-RPC formats. You search for typos in your tool names. Hours pass.

The tools are fine. The server is fine. Anthropic just cannot reach localhost:9000 from their data centers.

The Solutions

For production (recommended): Deploy your MCP server with a public hostname and TLS. In sh0, every server gets an auto-assigned domain with SSL (e.g., my-server.sh0.app). When the dashboard detects it is running on a public hostname, it sends the URL to the gateway and MCP mode activates automatically. All 30+ tools become available.

For local development: You need a fallback. sh0 detects localhost and shows a banner:

Local development mode -- limited AI tools. MCP mode requires a public hostname so Claude can reach your server.

The AI still works in local dev -- it falls back to a legacy tool-calling path where the dashboard executes tools via REST API calls. You get 24 tools instead of 30. The 6 missing tools are MCP-only features (like server-side web search and document fetching that Claude handles natively in MCP mode).

For other developers building MCP servers: Consider these options: 1. ngrok / Cloudflare Tunnel: Expose your localhost with a temporary public URL. Works, but adds latency and complexity. 2. Deploy to a dev server: Even a $5 VPS with a domain gives you full MCP. This is what we recommend. 3. Build a REST fallback: Like we did -- mirror your MCP tools as REST endpoints so a client-side executor can call them when MCP is unavailable. More work, but your product works everywhere.

The worst option is to let users think MCP is broken. We added the localhost detection banner specifically because the failure mode is silent. If you are building an MCP-enabled product, tell your users before they spend an hour debugging.

What the AI Knows Now

Beyond the tool gap, we enriched what the AI understands about the platform.

sh0 templates are not single containers. They are multi-service stacks. When you deploy wordpress, you get WordPress + MySQL + phpMyAdmin. When you deploy postgres, you get PostgreSQL + dbGate. The AI previously had no idea. It would suggest creating separate apps for each component.

Now the system prompt includes:

Platform architecture: default stack, AI sandbox available to all users (including free plan), sub-services model
Stack architecture: templates bundle sub-services, internal networking, auto-generated credentials
Deploy terminology: how to interpret "deploy" requests (new app vs. redeploy vs. template vs. compose)

The AI went from "I can list your apps and restart them" to "I can deploy a WordPress stack with MySQL and phpMyAdmin, run commands in a sandbox to debug it, check connectivity between services, and read your config files."

The Methodology Lesson

This bug was invisible to every individual test suite. The MCP server tests passed. The dashboard build passed. The gateway type-check passed. The tools were correct in isolation.

The bug lived in the integration. The dashboard assumed legacy mode. The gateway assumed MCP was configured. The MCP server assumed someone was connecting to it. Each system was right about its own behavior and wrong about the whole.

This is why the ZeroSuite methodology requires fresh-context audits. The developer who built the MCP server (me, five sessions ago) was too close to the MCP path to notice the legacy path was falling behind. A fresh session, prompted by user bug reports, saw the gap immediately.

Build. Audit. Audit. Ship. The methodology works because no single session has the full picture.

The Numbers

Metric	Before	After
Dashboard AI tools	15	24 (legacy) / 30 (MCP)
App creation tools	0	4
Sandbox tools	0	5
Sandbox REST endpoints	0	5
MCP fallback behavior	Docs-only (broken)	Legacy tools (correct)
Template knowledge	Names only	Full stack architecture

Takeaway

If your system has two paths to the same functionality, they will diverge. The legacy path will rot. The tests will pass. Users will file bugs that look like feature requests but are actually integration failures.

The fix is not "keep both paths in sync." The fix is to make one path primary and the other a fallback that inherits from the primary. MCP is our source of truth for tools. Legacy mirrors it. When MCP grows, we grow the mirror. When we forget, the user tells us.

That developer in the dashboard who asked the AI to deploy Redis? Next time, it will just work.

MCP Checklist for Developers

If you are building an MCP-enabled product, save yourself the debugging hours:

[ ] Your MCP server must be publicly reachable. localhost, 127.0.0.1, 0.0.0.0, and private IPs will not work with Anthropic's MCP Connector. Anthropic's servers must be able to HTTP POST to your MCP URL.
[ ] Use HTTPS. Anthropic's MCP client requires a secure connection for production use. Get a domain with TLS.
[ ] Detect localhost and inform the user. If window.location.hostname === 'localhost', show a banner explaining the limitation. Silent failure is the worst UX.
[ ] Build a REST fallback. Mirror your MCP tools as REST endpoints. When MCP is unavailable, your client can execute tools locally via REST. Your product works everywhere instead of only on deployed servers.
[ ] Test MCP with a real deployment, not localhost. Your local curl tests will pass. Your MCP tests will not. Set up a dev server with a public domain early.
[ ] Handle MCP failure gracefully. The connection can fail (timeout, DNS, TLS). Fall back to your REST tools, not to zero tools. catch (mcpError) { fallback() } -- not catch (mcpError) { docsOnlyMode() }.
[ ] Keep tool registries in sync. If you have both MCP tools and a legacy tool array, one will fall behind. Make MCP the source of truth and derive the legacy list from it, or at minimum audit for drift regularly.

MCP is powerful, but it comes with a deployment requirement that localhost development does not satisfy. Design for both paths from the start.