Phone tool gateway: one small, stable tool surface for a local model

The code is in gateway/. It runs on the PC behind mcpo, and Open WebUI on the phone talks to it as a single tool server. The measurements below come from one Intel Arc Pro B60 running Qwen3.8-27B, llama.cpp b11524 on Vulkan, on 2026-10-11.

What problem it solves

Qwen's chat template writes every tool schema at the start of the prompt (TOOL-CALLING.md). That has three consequences:

• Every loaded tool costs prompt tokens on every request.
• Changing the tool set throws away the prompt cache.
• Loading the whole PC agent, browser and desktop tools came to 18K tokens, and the first message took 39 s.

The gateway shows the model a fixed set of tools:

• seven pinned basics: pc_Read, pc_Grep, pc_Glob, fetch_fetch, time_get_current_time, skills and share_file;
• search_tools(query) and call_tool(name, arguments), which reach everything else.

Behind those, nine MCP servers serve about 100 tools: Claude Code's tools, the filesystem, fetch, time, library docs, a headless browser, the user's own Chrome, the Windows desktop and MarkItDown. A tool's schema costs nothing until a search returns it. The search result lands at the end of the conversation, so the cached prefix survives.

Phone eval (10 prompts, 2026-10-11)

gateway/tests/phone_eval.py gives Qwen the phone system prompt and the gateway's tools through mcpo. It has eight read tasks and two safety checks. Each case allows at most 8 model turns.

10/10 passed. Median 10.3 s per task, 149 s for all ten. 64,108 of 71,554 prompt tokens (90%) came from the cache. The first case includes a cold prefill of the tool set and system prompt (2,823 tokens). The model answered 8 of 10 cases with pinned tools alone, no search needed. It found the converter through search_tools on its first try. It stopped at the approval for the delete, and it reported the policy block on the gateway's config instead of working around it. Raw results: phone-eval-2026-10-11.json.

How it works

Startup

The old setup started eight stdio servers twice, once in mcpo and once inside the gateway. It also resolved npx and uvx packages on every start.

The new setup runs a single gateway behind mcpo, with the servers installed as executables. On the test PC:

• the gateway is ready in 18.6 s, down from about 100 s for the whole tool hub;
• mcpo answers in about 25 s.

BALANCED's idle model unload moved from 30 to 120 minutes, so the first message after a break is less likely to pay a 17 GB model load.

Install (Windows)

1. Create a venv in C:\AI\gateway and install the gateway: python -m venv .venv then .venv\Scripts\pip install fastmcp==3.4.8.
2. Copy gateway.example.json to gateway.json. Fix the paths, and put tokens such as PLAYWRIGHT_MCP_EXTENSION_TOKEN in the copy only, never in git.
3. Point mcpo at the gateway alone; see mcpo.config.json and start-mcpo.ps1.
4. Run set-approval-pin.ps1 on the PC to set the approval PIN. With no PIN set, nothing can be approved. On the approvals page, leave "Remember this device for 90 days" ticked and that device stays logged in for 90 days while its Tailscale IP is unchanged. Approving or denying a tool call still asks for the PIN on a remembered device; Studio and the rest do not. "Forget" on the page removes a device.
5. In Open WebUI, add the tool server and use Native function calling. connect_gw_openwebui.py does this from the command line.
6. Run the tests from gateway/: python tests/test_gateway.py (11 checks) and python -m unittest tests/test_outbox.py (27 tests).

Use it from Claude Code, Claude Desktop or Codex

An agent already has its own shell and file tools. What the gateway adds is the rest of the toolset: the headless browser, your logged-in Chrome, the Windows desktop, MarkItDown, library docs, skills and share_file. Those sit behind one search, and only six small schemas load up front. With a local model that matters most, because every schema is paid for on every request. With Claude it mainly keeps the tool list short.

1. Make an agent config from your gateway.json. This drops the pc server, which would be a nested Claude Code. Your tokens stay in the local file. ``powershell cd C:\AI\gateway; .\.venv\Scripts\python.exe make_agent_config.py ``
2. Give each agent its own approvals port and state folder. The phone instance behind mcpo already uses port 8093. A second instance on the same port starts without a page, and any change it asks for fails safe.

Claude Code (cloud Claude, or local Qwen through claude-qwen.cmd):

claude mcp add gw --scope user -e GW_APPROVAL_PORT=8094 -e GW_APPROVAL_URL=http://127.0.0.1:8094/approvals -e GW_STATE_DIR=C:\AI\gateway\state-claude -e PYTHONIOENCODING=utf-8 -- C:\AI\gateway\.venv\Scripts\python.exe C:\AI\gateway\gateway.py C:\AI\gateway\gateway.agent.json

With the agent config on the test PC, the gateway was ready in 51.8 s on its first start and 7.3 s on the next. Set MCP_TIMEOUT=90000 so Claude Code waits for it.

claude-qwen.cmd runs with --strict-mcp-config and only reads C:\AI\claude-local\mcp.json. For the local agent, add the same entry there:

"gw": { "command": "C:\\AI\\gateway\\.venv\\Scripts\\python.exe",
        "args": ["C:\\AI\\gateway\\gateway.py", "C:\\AI\\gateway\\gateway.agent.json"],
        "env": { "GW_APPROVAL_PORT": "8094", "GW_APPROVAL_URL": "http://127.0.0.1:8094/approvals",
                 "GW_STATE_DIR": "C:\\AI\\gateway\\state-claude", "PYTHONIOENCODING": "utf-8" } }

Claude Desktop: put the same "gw" entry under mcpServers in %APPDATA%\Claude\claude_desktop_config.json, then restart the app.

Codex (%USERPROFILE%\.codex\config.toml):

[mcp_servers.gw]
command = 'C:\AI\gateway\.venv\Scripts\python.exe'
args = ['C:\AI\gateway\gateway.py', 'C:\AI\gateway\gateway.agent.json']
startup_timeout_sec = 120

[mcp_servers.gw.env]
GW_APPROVAL_PORT = "8095"
GW_APPROVAL_URL = "http://127.0.0.1:8095/approvals"
GW_STATE_DIR = 'C:\AI\gateway\state-codex'
PYTHONIOENCODING = "utf-8"

With codex-qwen.cmd, switch off the servers the gateway already covers. For example, add -c mcp_servers.local-ai-playwright.enabled=false -c mcp_servers.local-ai-context7.enabled=false to MCPOFF.

How it behaves in an agent: reads run at once. A desktop click, a browser action or a delete returns NEEDS APPROVAL with a request id. Approve it on that agent's page, for example http://127.0.0.1:8094/approvals, using the same PIN, and the agent repeats the call. The kill switch (C:\AI\gateway\KILL) stops every instance.

Limits and next steps

• The eval cases are single-step jobs. Multi-step builds ("make me a website") still depend on the model working through a long loop in Open WebUI. The next step is a server-side agent tool, a plan-act-verify loop inside the gateway with its own todo list and the same guard; see the harness plan.
• Each search-then-call costs one more model turn. Pinning the most-used tools avoids that for reads.
• Anyone on the tailnet who holds a share link can fetch that file until it expires.