What is MCPgraphy?
MCPgraphy is a proxy that sits between an agent and an MCP server, learning which tools work from the resource states the agent encounters. It adds state-aware guidance to calls and can warn about or block calls that its observations indicate may fail. It is for developers running agents against stateful MCP servers who want to reduce invalid or risky tool calls without probing the server.
MCPgraphy Features:
Passive State Learning: MCPgraphy reads a resource before and after the agent's calls, then uses those observations to build a graph of states and tool outcomes.
State Affordances: The agent can ask which tools are candidates, approval-required, unsupported from the current state, or still untested for a resource.
Warnings and Blocking: Choose a warn policy that passes calls with notes about observed failures, or a block policy that stops calls before they reach the server.
Decision Explanations: For a proposed guard, the agent can inspect supporting observations, counterexamples, and what has not yet been tried.
Graph and Status: MCPgraphy exposes the learned graph as JSON or Mermaid and provides a status tool for recorded calls, warnings, blocks, and model version.
Persistent Audit: The proxy saves its log, graph, and decisions in SQLite so its learning remains available after a restart and its actions can be reviewed.
Server Adapters: A JSON adapter identifies how to read a resource and its ID, and the proxy can wrap downstream servers over stdio or Streamable HTTP.
MCPgraphy Benefits:
Fewer Failed Calls: Agents can avoid repeating actions that have already failed from the same observed state, spending less effort on rejected calls.
Safer Changes: Approval gates and evidence-based blocking give teams a way to stop destructive or unsupported actions before the server receives them.
Clearer Decisions: Observations and explanations make it easier to understand why an action was warned about or refused, rather than leaving the agent with an unexplained failure.
Honest Unknowns: Untested tools remain identified as unknown, helping agents avoid treating a lack of evidence as proof that an action is safe.
Reviewable Runs: Persisted decisions and logs give developers a record to inspect when checking what the proxy learned and how it handled calls.
Use Cases:
Filesystem Agents: Put MCPgraphy in front of a filesystem server when an agent edits, moves, or creates files and should catch mistakes such as acting on a missing file.
Release Workflows: Use it with a stateful release pipeline where publishing depends on prior steps, such as running tests before a release can be published.
Ticket Management: Run an agent against a ticket tracker when available actions depend on the ticket's state, such as whether it is already closed.
Destructive Tool Review: Require approval for destructive or selected mutating tools when agents can change resources that should not be altered without review.
MCP Agent Testing: Inspect the learned graph and decision history while evaluating how an agent handles state changes, rejected actions, or server behavior drift.

