The MCP observability stack is growing in the wrong direction. Sentry launched MCP server monitoring. Grafana built MCP observability dashboards. Datadog, Rollbar, Prometheus - they all added MCP integrations in early 2026. Every one of them monitors the AI agent from the outside. None of them give the agent a log store it can use.
LogPiper is a different kind of tool for MCP agents. It's not an observability dashboard. It's not a metrics collector. It's not an MCP tool either. It's a logging service (plain HTTP routes, a query engine and an SSE stream) that the AI agent writes to and reads from directly. The agent is both producer and consumer of the data. The "logging service for agents" pattern works differently from "monitoring for MCP," and LogPiper's architecture shows why.
Outside-In vs. Inside-Out
The distinction matters because it determines who benefits from the data.
Outside-in tools (Sentry, Datadog, Grafana, OpenTelemetry): These instrument the MCP server or transport layer. They track tool call counts, latency percentiles, error rates, token throughput. The data flows into dashboards that ops teams read. The AI agent never sees it. An MCP server monitored by Sentry knows its p99 latency. The AI agent calling that server doesn't.
Inside-out tools (LogPiper): The AI agent writes structured log entries. The AI agent queries them. The data lives in a store the agent can access through the same HTTP protocol it already uses. Not a monitoring dashboard for humans. Infrastructure for agents.
This isn't a criticism of outside-in tools. They're solving a real problem. Production MCP deployments need monitoring. You need to know when your tool server is dropping requests, when latency spikes, when error rates climb. Sentry does this well. Datadog does this well.
LogPiper solves a different problem: giving an AI coding agent structured runtime data during development. The agent instruments code with log POSTs, reproduces the failure, queries the structured errors, reads the exact HTTP bodies, and fixes the code. That's a feedback loop. Outside-in monitoring gives you a graph. Inside-out logging gives the agent a conversation with the runtime.
The Architecture
LogPiper is a handful of HTTP routes plus a query engine. No SDK, no client library, no protocol beyond HTTP and JSON.
Ingestion
POST /v1/logs accepts a single JSON entry or an array of them and returns {"ok": true, "count": N}. A batch is all-or-nothing: one malformed entry fails the whole request with a 400. From the same Mac no token is needed, so any local process can write. The design is fire-and-forget: a 2-second timeout, no retries, and a bare exception catch on the client side. Logging never blocks your application.
curl -X POST http://127.0.0.1:9998/v1/logs \
-H "Content-Type: application/json" \
-d '{
"source": "my-app",
"level": "error",
"event": "api.timeout",
"message": "Model inference exceeded 30s limit",
"data": {"model": "llama-3.2-3b", "durationMs": 31200},
"correlationId": "job_abc123"
}'Query
GET /v1/logs returns a JSON array of the newest matching entries, oldest first, and needs no token from the same Mac. Filters narrow the results (there's no time-range or text search):
level- minimum severity (debug, info, warn, error)source- origin app or script nameevent- prefix match (event=httpmatcheshttp.request,http.response,http.error)correlationId- exact match on an ID your code setexcludeSource/excludeEvent- comma-separated sources or event prefixes to droplimit- max entries to return (default 100, capped at 2,000)
# Recent errors from any source
curl "http://127.0.0.1:9998/v1/logs?level=error&limit=20"
# Everything your code tagged with one job ID
curl "http://127.0.0.1:9998/v1/logs?correlationId=job_abc123"
# MCP tool calls ToolPiper served
curl "http://127.0.0.1:9998/v1/logs?event=mcp&limit=50"Stream
GET /v1/logs/stream is an SSE endpoint, also token-free from the same Mac. Open it with level, source or event filters (plus the two exclude lists; correlationId isn't supported on the stream) and matching entries arrive the moment they're ingested. No polling. An AI agent or monitoring script can subscribe to errors in real time.
Storage
In-memory circular buffer. 5,000 entries. Oldest evicted first. Nothing survives a ToolPiper restart. Export the buffer to JSON on demand with POST /v1/logs/export, which takes a bearer token. This keeps the system fast and prevents disk bloat. LogPiper is a debugging scratchpad, not a time-series database.
The data flow is simple enough to draw:
AI Agent (Claude Code, Cursor, any HTTP client)
| POST /v1/logs
v
LogPiper (in ToolPiper, port 9998)
| stored in circular buffer
v
AI Agent
| GET /v1/logs?level=error
v
Structured error data, with the bodies your code loggedWhy HTTP and Not MCP Protocol
LogPiper's ingestion endpoints are plain HTTP, not MCP tool calls. This is deliberate.
MCP tool calls go through the AI client's tool-use machinery. The client formats the tool invocation as tokens, sends them to the model, the model generates the call, the client executes it. That's token cost, round-trip latency, and rate limits. For a logging endpoint that needs to handle thousands of writes per minute, MCP protocol overhead is unacceptable.
A requests.post() call from instrumented Python code costs nothing and takes single-digit milliseconds. A fetch() from a browser extension, a curl from a shell script, a URLSession.data() from Swift - they all hit the same HTTP endpoint with the same latency profile. No model in the loop. No token budget consumed.
The implication: LogPiper works without an MCP connection. It's reachable from any process on the same Mac via HTTP. No MCP tool reads or writes it; the AI agent calls it directly with curl or fetch. ToolPiper's MCP tools (status, models, chat) are the high-level control plane. LogPiper is low-level data plane infrastructure that any process, MCP-connected or not, can use.
The design principle generalizes: use HTTP for the data plane, MCP for the control plane. High-frequency data (logs, metrics, streaming responses) should flow over direct HTTP. Low-frequency commands ("load this model," "run this test," "take a browser snapshot") are fine as MCP tool calls.
The LogEntry Schema
The seven fields below carry the meaning; an entry can also hold durationMs and its own id. Every field is optional on ingest. ToolPiper fills in an id, the current time, source unknown, level info and event custom when they're missing.
| Field | Type | Purpose |
|---|---|---|
timestamp | ISO 8601 string | When it happened. Auto-set to now if omitted. |
source | string | Origin app or script. Your app name goes here. Used for ?source= filtering. |
level | enum | debug, info, warn, error. Comparable severity. ?level=warn returns warn + error. Any other value on ingest, warning included, fails the request with a 400. |
event | string | Dot-prefixed taxonomy. http.request, tool.crash, myapp.queue.stall. Prefix-matched on query. |
message | string | Human-readable description. Optional. Useful when the AI queries raw text. |
data | JSON object | Arbitrary payload. Request bodies, config state, timing, error details. The interesting part. |
correlationId | string | Groups related entries. Your code sets it; nothing assigns one for you. Exact-matched on query. |
The event prefix system is the key design choice. event=http matches http.request, http.response, http.error. event=tool matches tool.start, tool.stop, tool.output, tool.crash. You get hierarchical filtering without a separate tag system, without a label taxonomy, without any schema to define upfront. The event string is free-form. Your apps can use any prefix scheme: myapp.auth.login, myapp.queue.stall, deploy.staging.rollback.
HTTP Body Capture
Bodies are where the answer usually is, so it matters who records them. Your own code is the reliable source: put the request and the response in data and ToolPiper stores them untruncated (the only cap is 25 MB per request). The ModelPiper web app does this for itself when you run it locally, logging every HTTP call it makes with bodies truncated at 8,000 characters and credential-named JSON keys replaced with [REDACTED].
ToolPiper's own traffic is logged more thinly. The server writes one request line per call, and nothing captures the bodies of local model inference. The cloud proxy records the URL, method and whether the call streamed, and keeps the upstream error body (up to 8,192 characters) only when a streaming call returns 400 or above. So when a streaming cloud call returns a 400 because the tool schema has an unsupported keyword, that rejection message is in the log verbatim. MCP tool calls log the tool name and arguments with credential keys masked, then duration and success. Tool outputs aren't logged.
The agent that wants to see what was sent to the model logs it, then queries it back. It doesn't need to guess why the API returned a 422: the validation error is in the response body it logged.
// api.request entry your code posted
{
"source": "my-app",
"event": "api.request",
"data": {
"url": "http://127.0.0.1:9998/v1/chat/completions",
"requestBody": {"model": "llama-3.2-3b", "messages": [{"role": "user", "content": "Summarize this document"}]}
}
}
// api.error entry for the same call
{
"source": "my-app",
"level": "error",
"event": "api.error",
"durationMs": 12,
"data": {
"status": 400,
"responseBody": "{\"error\":{\"message\":\"...\"}}"
}
}In the web app, streaming responses log their status with isStreaming: true and no body, and binary responses show type and size instead of a body. If a streamed reply matters to your bug, log it yourself when the stream ends.
Correlation IDs
A correlation ID is a string your code sets. Put the same one on every entry a job writes, and one query returns the job's timeline across every process that used it. No timestamp correlation. No grepping across log files.
# Everything tagged with job_7f2a1
curl "http://127.0.0.1:9998/v1/logs?correlationId=job_7f2a1"Nothing assigns these for you. ToolPiper's own events and the web app's HTTP events carry no correlation ID, so grouping is something your code opts into: assign a job ID when the work starts, include it in every log POST, and the multi-step execution becomes a single queryable unit. ToolPiper's All Logs view has an Execution picker that filters on the same field. This is how you trace a request through three services without building distributed tracing infrastructure.
What We Didn't Build (and Why)
No persistence to disk. LogPiper is a debugging tool, not an audit log. In-memory keeps it fast and avoids disk bloat, and a ToolPiper restart starts it empty. The 5,000-entry circular buffer handles hours of active debugging. If you need a snapshot, POST /v1/logs/export writes the buffer to ~/Library/Application Support/ToolPiper/exports/ as JSON and returns the file's path. Persistence isn't built in because we've seen what happens when logging tools grow into log management platforms. They get slow. LogPiper stays fast by not trying to be Elasticsearch.
No token on the loopback path. Any process on the same Mac should be able to log without credential management. POST /v1/logs, GET /v1/logs and GET /v1/logs/stream take no token and no handshake when the connection comes from the Mac itself. The two routes that wipe or write out data are different: /v1/logs/clear and /v1/logs/export need a bearer token (tp_...) with the system:control scope, even from the same Mac. The trade-off: convenience vs. security. The waiver applies only to connections from the Mac itself, which makes this acceptable for a development tool. If you're running ToolPiper on a machine where untrusted processes might inject fake log entries, you have bigger problems than logging.
No MCP-specific ingestion format. Log entries are generic JSON. They don't know about MCP tools, tool schemas, or MCP sessions. They don't carry MCP-specific metadata. This keeps the system usable by non-MCP processes - shell scripts, CI runners, browser extensions, native apps. ToolPiper still logs the MCP tool calls it serves as its own entries: mcp.tools.call with the tool name and arguments (credential keys masked), then mcp.tool.complete or mcp.tool.error with duration and success. The outputs aren't logged.
No dashboard. The interface agents use is HTTP. For humans, ToolPiper's main window has an All Logs view: search across event, message and source, Level, Source and Execution pickers, a detail panel for the data payload, and Copy Logs and Clear Logs. That's a viewer, not a dashboard. If you want charts, pipe the SSE stream into jq or build your own on the JSON. We'd rather spend the engineering time on the query engine than on a dashboard that competes with tools developers already use.
The Bidirectional Pattern
Most developer tools are unidirectional. You configure them, and they produce output you read. Sentry captures errors you view in a dashboard. Datadog collects metrics you graph. The data flows one way: from the system to the human.
LogPiper is bidirectional. The agent writes data AND reads it back. The agent is the producer and the consumer. This creates a feedback loop that unidirectional tools can't replicate.
In practice, it looks like this:
- The AI agent writes code with log instrumentation (
POST /v1/logscalls at key points) - The code runs and fails
- The agent queries the log store (
GET /v1/logs?level=error) - The agent reads the exact error, including the response body it logged that explains the failure
- The agent fixes the code with real data, not a guess
- Repeat until clean
The critical step is 3 to 4. The agent's fix quality depends entirely on the data quality at the query step. Terminal output gives the agent a fragment. LogPiper gives it the full picture: structured fields, the bodies it logged, correlation IDs it set across processes, and precise filtering so the agent finds the relevant entries without parsing noise.
The bidirectional pattern is what makes LogPiper different from both outside-in monitoring and ephemeral debug logs. Sentry is write-only from the agent's perspective. Cursor Debug Mode is bidirectional but ephemeral. LogPiper is bidirectional and keeps entries until the buffer rolls past them or ToolPiper restarts. The agent can write a log at 10 AM, query it at 2 PM, and on a quiet buffer the entry is still there.
Lessons for MCP Tool Builders
Building LogPiper surfaced three design principles that apply to any MCP tool that handles high-frequency data.
1. Give the agent infrastructure, not endpoints. An MCP tool the agent calls once is useful. A service the agent writes to continuously and queries on demand is more useful. The difference is the relationship: a tool is a transaction, infrastructure is a resource the agent can lean on across an entire debugging session. When you're designing an MCP tool, ask whether the agent would benefit from persistent state it can query later. If yes, you're building infrastructure.
2. HTTP beats MCP protocol for the data plane. Log ingestion happens thousands of times per minute. MCP tool calls are expensive - they consume tokens, require model inference for tool selection, and go through the client's rate limiting. Use HTTP for high-frequency data (logging, streaming, metrics). Use MCP for low-frequency control ("load a model," "take a snapshot," "run a test"). The protocols serve different layers. Mixing them up means paying model inference costs for what should be a direct HTTP POST.
3. Bidirectional beats unidirectional. An agent that can only read data is limited. An agent that can write data AND read it back can build feedback loops. The write-query-act cycle is the pattern that turns AI assistants from code generators into debugging partners. If your MCP tool produces data, consider whether the agent should also be able to write to the same store. If it can, you've built a feedback loop. If it can't, you've built a dashboard.
Where LogPiper Fits in the Stack
The MCP observability space is splitting into layers, and they're complementary.
Transport observability (OpenTelemetry for MCP): Traces MCP requests across client and server. Distributed tracing for MCP deployments. Useful for understanding how tool calls flow through a production system. The agent doesn't interact with this layer.
Production monitoring (Sentry, Datadog, Grafana): Error tracking, latency dashboards, alerting. Ops teams use this to keep MCP servers healthy. The agent can query some of this through MCP integrations, but the data is aggregate, not instance-specific.
Agent-native logging (LogPiper): A log store the agent writes to and reads from. Development-time debugging. Instance-specific data - the exact payloads it logged, the exact error messages, the exact sequence of events that led to a failure. Not aggregate. Not for ops. For the agent that's trying to fix the code right now.
You probably need all three in a mature MCP deployment. OpenTelemetry for the infra team. Sentry for the ops team. LogPiper for the AI agent that's building and debugging the system.
Limitations
LogPiper runs on localhost only. It's not distributed. If your debugging problem spans two machines, LogPiper covers the local one.
The 5,000-entry buffer is fixed. For a focused debugging session, it's enough. For a process that generates thousands of entries per minute, you'll need to query frequently or export periodically.
The agent still has to be told to check the logs. It won't do this automatically. You can put "query LogPiper before guessing" in your CLAUDE.md or system prompt, and the AI will follow the instruction. But automatic log-check-on-failure is a workflow improvement that doesn't exist yet. The human closes the loop by prompting the query.
macOS only, because ToolPiper is macOS only. Linux and Windows developers can't use this today.
ToolPiper is a free download from the modelpiper.com/download. LogPiper is included in every installation.
This is spoke 5 in the vibe debugging content cluster. For a step-by-step Claude Code integration, see How to Debug with Claude Code Using a Local Log Bus. For the full LogPiper endpoint reference, see LogPiper: A Universal Logging Bus That Ships Free Inside ToolPiper.
