Recipe 7 — An MCP agent¶
Goal¶
Give the agent a capability that lives outside its process, reached over the Model Context Protocol. Recipe 5's tool was a Go function call inside LocalAGI; this one crosses a boundary you can firewall, restart and audit independently.
Architecture¶
flowchart TB
U["client"]
subgraph AG["localagi pod"]
LOOP["agent loop"]
BI["built-in actions<br/>40, in-process"]
MC["MCP client<br/>go-sdk v1.2.0"]
end
subgraph MT["mcp-time pod"]
PX["mcp-proxy<br/>SSE endpoint"]
TS["mcp-server-time<br/>stdio child"]
end
subgraph LAI["local-ai pod"]
CHAT["/chat/completions"]
end
U -->|"HTTP /v1/responses"| LOOP
LOOP -.->|in-process| BI
LOOP -.->|in-process| MC
MC -->|"SSE + POST /messages/"| PX
PX -.->|"stdio pipes"| TS
LOOP -->|"HTTP"| CHAT
Note the two hops on the right. LocalAGI speaks HTTP to mcp-proxy; mcp-proxy speaks stdio to
the actual server. The reason for that bridge is the most practical finding in this recipe.
What you will learn¶
- MCP is a transport and discovery mechanism, not a decision-maker
- which transport LocalAGI actually speaks, and its fallback
- why the
npx/uvxreference-server ecosystem cannot run as a stdio child of LocalAGI - that tool discovery happens at agent start, so a server that is not up yet leaves the agent silently short of tools
- that MCP tools are indistinguishable from built-in actions once the model sees them
Components¶
| Component | Role | Port |
|---|---|---|
| LocalAI | inference | 8080 |
| LocalAGI | agent loop, MCP client | 3000 |
mcp-proxy |
stdio → SSE bridge | 8080 |
mcp-server-time |
the capability: get_current_time, convert_time |
stdio child |
Prerequisites¶
- Recipe 5 completed. MCP changes only where a tool lives, so debug tool calling with a built-in action first
- A running stack. This recipe was validated on Kubernetes; the same agent configuration works under Compose with the MCP server as another service
Versions tested¶
tested:
date: 2026-08-17
versions:
localai: "v4.8.2-gpu-nvidia-cuda-12"
localagi: "v2.8.1 (image)"
mcp_proxy: "0.12.0"
mcp_server_time: "2026.8.18"
mcp_go_sdk: "v1.2.0 (pinned by LocalAGI)"
environment:
platform: kubernetes, k0s v1.34.3
node: bare metal amd64, NVIDIA Quadro RTX 6000
transport: SSE (Streamable HTTP attempted first, then fell back)
results:
tool_discovery: pass
get_current_time: pass — 2.6 s
convert_time: pass
cross_pod_boundary_confirmed: yes
Start the environment¶
The MCP server runs as its own workload:
Why a bridge, and not just cmd: npx ...
mcp-server-time speaks stdio only — its documented invocation is docker run -i, and it
has no --transport flag. LocalAGI can run stdio servers, but as child processes of its
own container, and the v2.8.1 image contains no runtime to run them with:
node MISSING npx MISSING python3 MISSING uvx MISSING
bash /usr/bin/bash curl /usr/bin/curl docker /usr/bin/docker git /usr/bin/git
So the whole npx @modelcontextprotocol/server-* and uvx mcp-server-* ecosystem — which is
most reference servers — cannot run as a stdio child of LocalAGI as shipped.
Three ways out, in preference order:
| Approach | Trade-off |
|---|---|
| Bridge to HTTP, as here | server gets its own lifecycle and is network-policyable. Recommended |
mcp_prepare_script |
runs /bin/bash -c <script> before MCP setup, so it can install a runtime or fetch a static binary into the container |
| Custom LocalAGI image | adds a build step you now own |
A statically linked Go or Rust MCP server needs none of this and works as a stdio child directly.
Verify each dependency¶
1. Tool calling already works. Do not debug MCP against an agent that cannot call a local tool.
2. The MCP server is serving. Its own log states the endpoint:
mcp-proxy 0.12.0
mcp-server-time 2026.8.18
[I] Serving MCP Servers via SSE:
[I] - http://0.0.0.0:8080/sse
INFO: Uvicorn running on http://0.0.0.0:8080
3. It is reachable from the agent's pod, which is where DNS and NetworkPolicy apply:
An SSE endpoint holds the connection open, so curl exiting with code 28 (timeout) is success
here. A connection refused is the failure you are looking for.
Configure the system¶
Create the agent only after the server is serving — see the note below.
curl -s -X POST http://localhost:18081/api/agent/create \
-H 'Content-Type: application/json' \
-d '{
"name": "mcp-probe",
"model": "qwen3-1.7b",
"system_prompt": "You use external tools when asked. Be terse and factual.",
"strip_thinking_tags": true,
"mcp_servers": [{"url": "http://mcp-time:8080/sse"}],
"max_attempts": 1
}'
mcp_servers takes {url, token}. token is omitted here because the server is unauthenticated
on an internal network; when you set it, remember it is stored in plain text in the agent's
JSON on disk.
The stdio form is a separate list:
"mcp_stdio_servers": [{"name": "files", "cmd": "/usr/local/bin/server", "args": ["--root", "/data"], "env": ["LOG_LEVEL=info"]}]
| Transport | Field | Server lifetime | Fails as |
|---|---|---|---|
| HTTP | mcp_servers |
independent | connection refused, 401, timeout |
| stdio | mcp_stdio_servers |
child process of LocalAGI | exec failure, immediate exit, protocol error |
Discovery happens at agent start — ordering is load-bearing
We hit this on the first attempt. The agent was created at 23:24:51; the MCP server only
began serving at 23:24:55, four seconds later. Result:
ERROR Failed to connect to MCP server via SSEClientTransport
server="{URL:http://mcp-time:8080/sse Token:}"
error="dial tcp 10.96.16.69:8080: connect: connection refused"
INFO Done populating actions from MCP Servers
INFO Agent started name=mcp-probe
Note the last two lines: the agent started successfully with no MCP tools, and answered requests normally without them. The error is logged at ERROR level, but nothing fails.
Tools are not re-discovered later. Delete and recreate the agent after the server is up:
Run the request¶
Ask for something the model cannot know without the tool:
curl -s http://localhost:18081/v1/responses \
-H 'Content-Type: application/json' \
-d '{"model":"mcp-probe","input":"What is the current time in Asia/Tokyo? Use your tools."}' \
| jq -r '.output[0].content[0].text'
Then read what actually ran:
Expected result¶
The current time in Asia/Tokyo is **08:26 AM** (Saturday, 22 August 2026).
No daylight saving time adjustments are in effect.
Latency 2.6 s on a GPU-backed LocalAI. And the history:
Reasoning:
Action taken: get_current_time
Parameters: {"timezone":"Asia/Tokyo"}
Result: {
"timezone": "Asia/Tokyo",
"datetime": "2026-08-22T08:26:14+09:00",
"day_of_week": "Saturday",
"is_dst": false
The second tool works the same way:
curl -s http://localhost:18081/v1/responses \
-H 'Content-Type: application/json' \
-d '{"model":"mcp-probe","input":"Convert 09:00 from Europe/Rome to America/New_York using your tools."}' \
| jq -r '.output[0].content[0].text'
Observed: 03:00, a -6.0h difference — correct for August, when Rome is UTC+2 and New York is
UTC−4.
History does not distinguish MCP tools from built-in actions
Compare that entry with Recipe 5's counter entry: same
shape, same fields, no marker saying one crossed a process boundary and the other did not.
That is the design. By the time the model chooses, both are just tools with JSON schemas — and it is also why MCP is a trust boundary and not a permission boundary.
What happened internally¶
- At agent start, LocalAGI constructs an MCP client and tries
StreamableClientTransportagainst the configured URL. (network HTTP) - That fails against this
/sseendpoint, so it falls back toSSEClientTransport. (network HTTP) —core/agent/mcp.go:158-166 - It opens an SSE stream and lists the server's tools.
mcp-proxyforwards the request over stdio pipes tomcp-server-time. (stdio, inside the mcp-time pod) - Each discovered tool is wrapped as an ordinary agent action carrying the schema the server
advertised. Logged:
Done populating actions from MCP Servers. (in-process) - On a request, the wrapped MCP tools are offered to the model in the same list as the 40 built-in actions. (in-process)
- The loop calls
/chat/completions. (network HTTP → gRPC) - The model emits
get_current_time{timezone: "Asia/Tokyo"}. It cannot tell this tool is remote. - The wrapper issues an MCP tool call. On the SSE transport, client→server messages go as
POST /messages/?session_id=<id>while responses arrive on the open stream. (network HTTP) mcp-proxyrelays it over stdio; the server answers with JSON. (stdio)- The result is appended as an observation and the loop continues. (in-process)
Steps 1–4 were confirmed from LocalAGI's log and the source; step 8 from the server's access log (below). The internal stdio framing between proxy and server was not traced.
Request flow¶
sequenceDiagram
participant C as client
participant AG as LocalAGI
participant PX as mcp-proxy
participant TS as mcp-server-time
participant AI as LocalAI
Note over AG,TS: at agent start
AG->>PX: StreamableClientTransport connect
PX--xAG: fails
AG->>PX: SSEClientTransport connect
PX->>TS: spawn / stdio
AG->>PX: list tools
PX->>TS: list tools (stdio)
TS-->>PX: get_current_time, convert_time
PX-->>AG: tool schemas
C->>AG: POST /v1/responses
AG->>AI: POST /chat/completions (all tools offered)
AI-->>AG: get_current_time{Asia/Tokyo}
AG->>PX: POST /messages/?session_id=…
PX->>TS: tool call (stdio)
TS-->>PX: {"datetime":"2026-08-22T08:26:14+09:00",…}
PX-->>AG: result on the SSE stream
AG->>AI: POST /chat/completions (with observation)
AI-->>AG: prose
AG-->>C: Responses envelope
Persistent state¶
| What | Written by | Where | Survives restart |
|---|---|---|---|
| MCP server configuration | LocalAGI pool | /pool JSON, including any token in plain text |
yes |
| Discovered tool schemas | LocalAGI, in memory | memory | no — re-discovered at agent start |
| Whatever the MCP tool changed | the MCP server | wherever it stores things | outside this stack |
The time server is stateless, which is part of why it is the right first MCP server. A server
that writes things puts its side effects outside your backups and outside
kubectl delete namespace — see security.
Logs worth inspecting¶
The discovery result. Failed to connect to MCP server via … means this agent has fewer tools than
you think.
The other side of the boundary — and the proof it was crossed:
10.244.172.216 is the LocalAGI pod's IP:
Matching those two is how you prove the hop happened rather than assuming it.
Ground truth for arguments and results — last ten only, in memory.
Failure modes¶
The agent has no MCP tools and answers vaguely.
- Symptom: plausible answers, empty
History, no MCP lines in the log. - Cause: discovery failed at agent start — most often the server was not up yet.
- Check:
kubectl -n localai-stack logs deploy/localagi | grep -i mcp - Fix: bring the server up, then delete and recreate the agent. Restarting the agent's pod also re-runs discovery.
connection refused in the discovery error.
- Cause: wrong Service name or port, or the server not listening on
0.0.0.0. - Check:
kubectl -n localai-stack exec deploy/localagi -- curl -s --max-time 5 <url> - Fix:
mcp-proxydefaults to127.0.0.1; it needs--host=0.0.0.0to be reachable from another pod.
FileNotFoundError: 'uvx' in the MCP server's log.
- Cause: we hit this. The
ghcr.io/sparfenyuk/mcp-proxyimage does not bundleuv/uvx, somcp-proxy … uvx mcp-server-timecannot spawn its child. - Fix: use a base image that has the runtime and install both packages, as the shipped manifest does.
stdio server exits immediately.
- Cause:
cmdnot present in the LocalAGI container — the usual case, given no node or python. - Fix: bridge to HTTP, use
mcp_prepare_script, or use a static binary. Note that stdout is the protocol channel: a server that logs to stdout corrupts the stream, so its diagnostics must go to stderr.
401 from an HTTP server.
- Cause:
tokenwrong or absent. It is per-server, not global. - Fix: set
tokenin that entry ofmcp_servers.
The model never chooses the MCP tool.
- Cause: the same small-model limitation as Recipe 5, not an MCP problem. Note the tool description comes from the server, so you may not control it.
- Fix: verify with a built-in tool first; say "use your tools" in the prompt; try a larger model.
Troubleshooting¶
- Does inference work? LocalAI directly
- Does a built-in tool work? Recipe 5's
counter - Is the MCP server serving? its own log, and the endpoint it prints
- Is it reachable from the agent's pod?
exec … curl— timeout means success on SSE - Did LocalAGI discover the tools? the MCP log lines
- Did the model select one?
History - Did the server see the call? its access log, matched against the agent's pod IP
Step 2 is the one that saves the most time: if a local tool does not work, MCP cannot.
Cleanup¶
Deleting the agent stops any stdio child process and stops HTTP calls. It does not undo
anything an MCP tool did elsewhere — with time there is nothing to undo, which is the point of
starting here.
Variations¶
Both transports on one agent. mcp_servers and mcp_stdio_servers are independent lists;
tools from both merge into the same offered set.
Constrain a server that can actually do damage. Swap time for a filesystem server mounted
read-only, then ask the agent to write a file. It fails at the boundary, not in the prompt —
which is the whole argument of
the security model. MCP has no permission model of its own:
if the model can name the tool, it can call it with arguments it chose.
Demonstrate indirect prompt injection. Point a fetch-style server at a page you control
that contains instructions, and watch them reach the model as tool output. Worth doing once, on a
throwaway deployment, because it makes the threat concrete. Do not leave it enabled.
LocalAI as an MCP server. LocalAI v4.8.2 logs
LocalAI Assistant in-memory MCP server initialised tools=36 read_only=false — 36 administrative
tools over the model runtime, not read-only. We probed /mcp, /api/mcp and /mcp/sse and all
returned 404, so we found no default external path; treat it as a privilege surface for LocalAI's
own Assistant rather than something you connect an agent to.
Upstream references¶
- LocalAGI
core/agent/mcp.go—MCPServer{url, token}at 22-25 andMCPSTDIOServer{name, cmd, args, env}at 27-32;StreamableClientTransportthenSSEClientTransportfallback at 158-166;mcp_prepare_scriptvia/bin/bash -cat 184;exec.Command+CommandTransportfor stdio at 193-198. Validated against v2.9.0. - LocalAGI
core/state/config.go—mcp_servers,mcp_stdio_servers,mcp_prepare_script. - LocalAGI
go.mod—github.com/modelcontextprotocol/go-sdk v1.2.0. - Model Context Protocol specification — transports, tool discovery, and why stdout is the protocol channel.
mcp-server-time—get_current_time,convert_time,--local-timezone; stdio only.sparfenyuk/mcp-proxy— the stdio→SSE bridge,--host,--port,/sse.- Absence of node/npx/python3/uvx in the LocalAGI v2.8.1 image; the discovery-ordering failure and its log lines; the
uvxFileNotFoundError; both tool calls and their results; thePOST /messages/?session_id=access-log lines matched to the LocalAGI pod IP: observed 2026-08-17, see version matrix.