An MCP agent use case: from problem to shipped

Abstract advice about agents only goes so far. To make the patterns concrete, this post walks one realistic project from the messy original problem all the way to a shipped, monitored agent running against production systems through the Model Context Protocol. The scenario is composite — drawn from how teams actually build with Claude Code and the Claude Agent SDK — but every step is the real work, in the real order, with the real decisions you would face.

The problem: a mid-sized software company's support team spends hours a day on a single repetitive task. When a customer reports that their account is in a broken state — a failed billing sync, a stuck provisioning job — an engineer has to investigate across three systems (the billing API, the provisioning service, and an internal status database), figure out what went wrong, and either fix it or escalate. It is tedious, it is slow, and it is exactly the kind of bounded, well-understood work an agent can do — if you build it carefully.

Step 1: scope the problem honestly

The first decision is the most important one, and it is a scoping decision, not a technical one. We do not build "an agent that fixes support issues." That is unbounded and would fail. We build an agent that handles one specific, well-defined class of issue — stuck provisioning jobs — and does three things: investigate across the three systems, propose a remediation, and either apply a safe fix automatically or escalate to a human with a complete diagnosis.

This narrow scope is what makes the project tractable. We can enumerate the failure modes, define what "correct" looks like, and build an eval set. An agent with a job small enough to fully understand is an agent you can ship. The instinct to make it general is the instinct that kills agent projects.

Step 2: design the tool contracts

With scope fixed, we design the MCP tools the agent will use. This is where most of the real engineering happens. The agent gets read tools against all three systems — get_provisioning_status, get_billing_state, query_status_db — and exactly one carefully scoped write tool, retry_provisioning_job, which can only retry a job that is in a known-stuck state and only once.

Each tool description is written for a model to use correctly under ambiguity: precise about what it returns, explicit about its limits, and with error messages the model can recover from. The write tool's description states plainly that it must only be used after the read tools confirm the job is genuinely stuck, and that it must never be called twice for the same job. The narrowness of that write tool is the entire safety story of this agent.

flowchart TD
  A["Support ticket: stuck job"] --> B["Agent reads 3 systems via MCP"]
  B --> C{"Diagnosis clear?"}
  C -->|No| D["Escalate with full trace"]
  C -->|Yes, safe retry| E{"Within action budget?"}
  E -->|No| D
  E -->|Yes| F["Call retry_provisioning_job"]
  F --> G["Verify fix & close ticket"]
  G --> H["Log full audit trail"]
  D --> H

Step 3: build the loop and the guardrails

Now we build the agent loop on the Claude Agent SDK. The system prompt establishes the agent's job, its boundaries, and the order of operations: always investigate with the read tools first, form a diagnosis, then decide between safe-fix and escalate. Critically, the boundaries are also enforced in code, not just in the prompt. A code-level guard rejects any call to the write tool unless the read tools have confirmed the stuck state in this same run, and a per-run action budget caps the agent at one write call. The prompt asks nicely; the code makes it true.

We also wire the audit trail from the start. Every run records the ticket, the full reasoning, every tool call with arguments and results, the diagnosis, and the outcome. This is not an afterthought we add before launch; it is part of the loop because it is how we will debug, eval, and prove correctness later.

Step 4: build the eval set before shipping

Before this agent touches production, we build an eval set from real historical tickets — stuck jobs that engineers have already resolved, so we know the right answer. We run the agent against them in a sandbox pointed at a replica, and we grade two things: did it reach the correct diagnosis, and did it choose the correct action (fix versus escalate)? We deliberately include hard cases — ambiguous tickets where the right move is to escalate, not fix — because the most important behavior to verify is that the agent escalates when it should rather than guessing.

The eval set is the gate. We do not ship until the agent reaches the correct diagnosis on the clear cases and, just as importantly, correctly escalates the ambiguous ones without ever applying a wrong fix. An agent that resolves 90% of tickets but occasionally applies the wrong fix to the other 10% is worse than useless; the eval is what catches that.

Step 5: stage the rollout

We ship in shadow mode first: the agent runs on real incoming tickets, produces a full diagnosis and a proposed action, but does nothing — a human reviews every proposal. For a couple of weeks we compare the agent's proposals to what the engineers actually do. This generates labeled data and, more importantly, builds justified confidence. When the agent's proposals match engineer judgment consistently, we let it apply the safe retry automatically while still escalating everything ambiguous to a human. The high-blast-radius path never goes fully autonomous.

Step 6: the shipped outcome and what it taught us

The shipped agent now handles the stuck-provisioning class end to end: most tickets resolved automatically in seconds, the genuinely ambiguous ones escalated to a human with a complete diagnosis already attached so the engineer starts halfway done. The win is not just the automated resolutions — it is that even the escalations are faster, because the human inherits the agent's investigation.

The lessons generalize. The narrow scope made the project shippable. The tool contracts and code-level guards made it safe. The eval set made it trustworthy. The staged rollout made it accepted by the team. None of those steps is glamorous, and skipping any one of them is how the same project would have failed. That is the real shape of shipping a production MCP agent: not a clever model, but a disciplined chain of unglamorous decisions.

Frequently asked questions

Why start with such a narrow agent scope?

A narrow scope is what makes the project tractable. With one well-defined class of work, you can enumerate failure modes, define correctness, build an eval set, and reason about blast radius. Broad "fix anything" agents fail because none of that is possible. You widen scope later, once the narrow version is proven.

What does shadow mode accomplish?

Shadow mode runs the agent on real tickets while a human reviews every proposal and the agent takes no real action. It surfaces failures safely, generates labeled data by comparing proposals to human decisions, and builds the justified confidence you need before granting autonomy — all without risking a wrong production action.

How many tools should a production agent have?

As few as the job requires, and write tools should be the minority. In this walkthrough the agent had three read tools and exactly one narrowly scoped write tool. Fewer, tighter tools mean a smaller blast radius and an easier-to-reason-about system. Every tool you add expands what can go wrong.

What is the most common reason these projects fail?

Skipping the unglamorous steps — scoping too broadly, enforcing limits only in the prompt instead of code, shipping without an eval set, or going straight to full autonomy. The model is rarely the problem. The discipline around it is what separates a shipped agent from a demo that never reaches production.

Bringing agentic AI to your phone lines

CallSphere takes this exact build discipline — narrow scope, scoped tools, real evals, staged rollout — and applies it to voice and chat agents that diagnose, act, and book work live on every call and message. See it shipped and running at callsphere.ai.

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.