Armature Instruments MCP Agent Sessions
Armature is a YC P26 project, founded by Theodore and Louis, that instruments Model Context Protocol servers and reconstructs the agent sessions behind their tool calls. It deals with a new blind spot: your MCP server may receive a clean tool call, but you often cannot see what the user asked Claude, ChatGPT, or Codex to do before that call happened. The takeaway is to treat MCP analytics as a narrow debugging receipt: useful for evals, triage, and to implement code review habits for ai-generated code, but only inside a deliberate permission and redaction boundary. For Codex users, it is a concrete engineering team ai adoption story: observe the agent boundary first, then decide what should be trusted.
See the session, not only the tool call
Armature’s pitch is simple: wrap your MCP server, then see reconstructed sessions in a dashboard. As described in the project’s Show HN post, the dashboard is meant to show the user request, the agent’s path to the MCP call, clustered use cases, and frequent issues that agents hit while using your tools. Gemini Workshop is part of Harness Institute.
An MCP session is the surrounding user-agent interaction that causes a tool call, not just the JSON request your server receives. That distinction matters because the same tool call can mean very different things.
Imagine a github_search_issues MCP tool. A raw log says the agent searched for billing retry webhook timeout. A reconstructed session might show whether the user asked for a bug fix, a support answer, a migration plan, or a risky production change. Those are different product analytics stories, and they are different review stories.
The trap is to treat this as ordinary server analytics. It is not. MCP traffic can carry prompts, customer data, repository names, file paths, issue text, and sometimes sensitive business context. If you instrument it like a clickstream, you will collect more than you meant to collect.
Be precise about “agent thoughts”
Armature says it reconstructs what the user asked the agent to do and what the agent thought. That is the interesting claim, and it is also the one engineers should inspect carefully.
As of August 2026, the safe reading is this: assume the product reconstructs agent session context from the data available around MCP tool calls and any integration surface the wrapped server can observe. Do not assume it receives private model chain-of-thought unless Armature’s docs and your agent provider’s contract explicitly say so.
That may sound fussy, but it is a useful line. In a real Codex workflow, you usually need enough context to answer, “Why did the agent touch this file?” You do not need secret reasoning tokens. A good review receipt can be boring: user request, tools called, files read, commands suggested, errors hit, and final diff.
The trap is to build policy around invisible cognition. Build around artifacts instead. For a coding agent, artifacts are the PR, the diff, the tests, the tool calls, and the handoff note.
Compare Armature with logs and transcripts
Armature sits between two familiar options: server logs and full chat transcripts. The useful question is not whether one is “better.” It is which receipt answers the review question with the least sensitive data.
| Criteria | Plain MCP server logs | Armature session analytics | Agent-side transcript review |
|---|---|---|---|
| What you see | Tool name, arguments, response, status, latency | Reconstructed sessions behind MCP calls, clustered use cases, frequent agent issues | The conversation as seen inside the agent surface, if export or history is available |
| Best use | Debugging a broken tool or slow endpoint | Finding which workflows agents actually attempt and where they fail | Reviewing a single high-risk task end to end |
| Main blind spot | No user intent before the call | Depends on what the wrapper can observe and what redaction removes | Often manual, hard to aggregate, and may include more sensitive content than needed |
| Review fit | Good for “did the API behave?” | Good for “why did agents use this tool this way?” | Good for “should this exact change be trusted?” |
| Risk to manage | Arguments may contain secrets or customer data | Session reconstruction can over-collect unless bounded | Full transcript capture can become a privacy and retention problem |
Verdict: Plain logs win for low-level operations, Armature wins when you need product analytics and evals for MCP usage, and transcript review wins for one-off sensitive investigations. For agentic coding, the best receipt is often a blend: aggregated MCP sessions to spot patterns, plus PR-level evidence for the exact code under review.
If you want the longer context around this release, we covered the same signal in Armature Adds Analytics for MCP Sessions. This piece focuses more on the boundary a Codex user should keep when an MCP server becomes observable.
Wire it to a safe MCP boundary
Start with a read-only MCP server. That is the cleanest way to learn what agents are doing without giving the analytics layer a path to mutate production systems.
A good first experiment is a repository-inspection MCP server for OpenAI Codex. Let it read issue metadata, PR metadata, and selected files. Keep writes, deploys, secrets, billing systems, and customer records out of scope.
A small AGENTS.md rule makes the boundary visible to the agent and to reviewers:
# MCP boundary
Use MCP tools for read-only repository context unless a task explicitly asks for a write.
Do not send secrets, customer data, access tokens, or private incident notes through MCP tools.
When you use an MCP tool for a code change, include the tool name and why it was needed in the PR handoff.
# Verification loop
Before proposing a patch, run the smallest relevant test command.
If tests cannot run locally, say why and name the command a reviewer should run.
That rule is not magic. It gives Codex a local contract and gives the human reviewer a receipt to check. If the PR handoff says “used repo search to inspect retry behavior,” the reviewer can compare that claim with the session analytics and the actual diff.
The trap is to wire analytics after writes are already allowed. Once an MCP server can create tickets, push branches, update databases, or trigger deployments, observability becomes incident response instead of learning.
For more on the review side of this problem, keep the broader AI coding governance topic nearby. The practical bit here is narrower: decide what your MCP server may see before you decide what dashboards should show.
Copy this MCP review checklist
Use this as a small experiment plan, not a program. One MCP server, one repo, one review loop, one week of sessions.
| Decision | Safe default | Upgrade only when |
|---|---|---|
| First MCP scope | Read-only repo and issue metadata | Reviewers can explain what data appears in session analytics |
| Data sent to analytics | Redacted prompts, tool calls, tool errors, non-secret file paths | You have a written retention rule and a way to disable collection |
| Agent permissions | Search, read, summarize | The review loop catches incorrect tool use reliably |
| PR evidence | Diff, tests run, MCP tools used, unresolved uncertainty | The agent consistently produces accurate handoffs |
Permission-boundary note: keep the first Armature-wrapped MCP server read-only, with client-side redaction enabled if available, and do not include secrets or customer records in tool arguments. If redaction is configurable, test it with fake tokens, fake emails, and fake customer IDs before any real session data leaves your environment.
Review checklist for a generated-code PR:
- Does the PR handoff name each MCP tool the agent used?
- Does the session show the same user intent described in the PR?
- Did the agent read enough local context, or did it patch from a shallow search?
- Are tool errors reflected in the final explanation, or quietly ignored?
- Did the agent run the smallest relevant test command?
- Is any generated code touching auth, payments, migrations, or deploy paths?
- Would this diff pass review if a junior engineer wrote it without AI?
This is also the most grounded answer to “what are the best ways to implement code review habits for ai-generated code?” Start with receipts that reviewers can verify. MCP analytics can reveal patterns, but approval still belongs to the diff, the tests, and the human review.
Common questions
What are the best ways to implement code review habits for ai-generated code?
Start by requiring a receipt for every generated-code PR: prompt summary, files changed, tools used, tests run, and known uncertainty. MCP session analytics can help verify the receipt, but they should not replace review. This belongs beside AI coding training for teams, not instead of it, because habits form around repeated PR evidence.
How is Armature actually getting the model’s thoughts?
Treat “agent thoughts” as reconstructed session context unless the product documentation proves a stronger claim. An MCP wrapper can observe tool calls and surrounding integration data, but private chain-of-thought is a separate provider and policy question. For reviews, you usually need user intent, tool sequence, errors, and final output more than hidden reasoning.
Does the three-line MCP wrapper claim hold up in a real project?
It may hold for the minimal SDK insertion, but production use is never only line count. You still need to check runtime placement, auth, redaction, sampling, retention, and failure behavior. Test it on a toy read-only MCP server first, then decide whether the observed session data is useful enough to justify wider instrumentation.
Can I disable collection or control redaction?
You should require both controls before using session analytics with real developer or customer data. The HN discussion raised exactly this concern: whether redaction is client-side, open, configurable, and disableable. Until those answers are clear in your environment, send only synthetic or low-sensitivity sessions through the wrapper.
Where does this fit with Cursor, Codex, and MCP?
It fits at the MCP server boundary, not inside a specific editor. Cursor, Anysphere’s AI code editor, can use agents that call tools; OpenAI Codex can work from repo instructions and command loops; MCP gives external tools a common integration surface. Armature’s bet is that the server side is a good place to observe agent behavior.
Best ways to use this research
- Best for: deciding whether an MCP server needs session-level analytics before you give coding agents broader access.
- Best first artifact: a read-only MCP boundary note in
AGENTS.md, plus a PR handoff that lists tool calls and tests. - Best comparison angle: compare Armature against plain MCP logs and full transcript review by asking which one answers the review question with the least sensitive data.
- Best safety move: verify redaction and disablement on fake data before wrapping a production MCP server.
Further reading
- Product analytics (and evals) for agent sessions on your MCP — source
- Model Context Protocol — specification
- Cursor — Agent
- OpenAI Codex
Try one narrow receipt
Wrap one read-only MCP server, inspect the sessions, and compare them with the next three generated-code PRs. If the receipt helps reviewers catch real issues without collecting sensitive data, keep going; if not, tighten the boundary before adding more tools.
One methodology lens
One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.