Best Practices for Building Production-Grade MCP Servers for AI Agents

prefect · Tech · 2026 · source Agentic: yes · promotional bias: low · source-backed · extracted with prompt 0.5.4 (schema v2)

Generated from extraction.json — do not edit by hand. Every claim cites verbatim source evidence; stated means the quote directly asserts the claim, implied means it supports it indirectly.

Problem

Domain: Production MCP server design for AI agents

Prefect's MCP guidance addresses a recurring production problem: teams expose API-shaped tool surfaces to agents, then discover that agents struggle with too many operations, complex arguments, thin documentation, and scarce context windows.

Constraints:

MCP tools are consumed by autonomous agents rather than humans
agents have limited context windows and usually receive tool descriptions at handshake
REST-style atomic operations can force the agent to become a slow, stochastic orchestrator
complex nested arguments and stale documentation confuse tool use
large tool catalogs can exhaust the agent's token budget before any task begins

Architecture

The recommended architecture treats an MCP server as an agent-facing product surface. Designers start from agent stories and outcomes, wrap multiple API calls behind a single outcome-oriented tool when the workflow is known, flatten arguments into top-level primitives and enums, write tool and server instructions as context, keep token budgets small, and curate tool catalogs instead of dumping every endpoint into the handshake.

Diagram confidence: reconstructed (reconstructed from prose).

flowchart LR
  agent-story[Agent story] --> outcome-tool[Outcome tool]
  outcome-tool --> flattened-arguments[Flattened arguments]
  flattened-arguments --> tool-documentation[Tool documentation]
  tool-documentation --> token-budget[Token budget]
  token-budget --> curated-tool-catalog[Curated tool catalog]
  outcome-tool --> backend-api-calls[Backend API calls]

Drag to pan · scroll or use +/− to zoom · reconstructed from the source's described component topology

Components

Component	Role	Interacts with
`Agent story`	Outcome-oriented description of what the autonomous agent is trying to accomplish.	`Outcome tool`
`Outcome tool`	Agent-facing MCP tool that hides known API choreography behind a task-level action.	`Agent story`, `Flattened arguments`, `Backend API calls`
`Flattened arguments`	Top-level primitive or enum parameters that reduce tool-call ambiguity.	`Outcome tool`, `Tool documentation`
`Tool documentation`	Server and tool instructions designed as context for the model.	`Flattened arguments`, `Token budget`
`Token budget`	Context-window constraint that limits how much tool surface can be exposed.	`Tool documentation`, `Curated tool catalog`
`Curated tool catalog`	Deliberately small set of tools selected for the current agent surface.	`Token budget`
`Backend API calls`	Existing service operations executed by server-side code rather than by the agent.	`Outcome tool`

Data flow

A developer translates a workflow into an agent story, exposes one outcome-oriented tool for that workflow, gives it flat typed arguments and documentation, and ships only the curated tool descriptions the agent needs at MCP handshake. When the agent invokes the tool, server-side code performs known API orchestration and returns the outcome without asking the model to stitch low-level calls together.

3 supporting quotes

“Instead, we want things like track latest order and give an email. It's hard to screw up and you know what the outcome is when you call it.”transcript, stated

“We made three calls in sequence that are configured that are to our API, but we buried them in one agentf facing tool.”transcript, stated

“when an when an LLM connects to an NCP server, it typically does download all the descriptions in one go so that it knows what's available to it.”transcript, stated

Why this architecture

The design keeps deterministic orchestration in code and leaves the agent with fewer, better-named choices. That reduces ambiguity, saves context, and avoids making the LLM infer workflows the server already knows how to execute.

3 supporting quotes

“agents are right in the middle because they can do it but it's expensive and slow and annoying and hard to debug and stochastic.”transcript, stated

“designed top down from the workflow, not bottom up from the API endpoints. Two different ways to get to the same place, but they”transcript, stated

“The the API calls still have to happen. There's no magic happening here. But the question is, are we going to ask an”transcript, stated

Models used: LLM agents · MCP clients · FastMCP

Scale

The speaker frames the guidance against MCP's rapid growth over the previous year.
“MCP has gone crazy in the last year, we found it actually to be constructive to position fast MCP uh as I'm maintaining”transcript, stated
A concrete token-budget example uses the GitHub MCP server shipping roughly 200,000 tokens at handshake.
“I think the meme right now is that the GitHub server ships like 200,000 tokens when you handshake with it, something like that.”transcript, stated
One customer wanted to expose 800 endpoints through MCP, illustrating how large enterprise APIs collide with context budgets.
“They had 800 endpoints that had to be exposed to which I had this thought, which if by the time you finish reading this, this is the token budget”transcript, stated

Alternatives considered (roads not taken)

Expose REST-style atomic operations directly

Rejected because: The speaker says that is good REST API design but bad MCP design because it forces agents to assemble outcomes from low-level calls.

“This is amazing if you're building a REST API. It is best practice if you're building a REST API. It is bad if you're building an MCP server.”transcript, stated

Use the agent as the orchestration layer for known workflows

Rejected because: Known API choreography should be handled by deterministic server-side code because LLM orchestration is expensive, slow, and hard to debug.

“Finding out an order status, really bad time, really expensive time to choose to use an LLM as your orchestration service.”transcript, stated

Expose nested dictionaries or object-shaped arguments

Rejected because: Complex arguments are harder for models and clients to handle; the guidance recommends top-level primitives and enums.

“Just don't ask your um LLM to invent complex arguments. Now you could ask what if it's a pyantic model with every field annotated and fine that's”transcript, stated

Patterns

`tool-use-orchestration` (agent-design)

MCP tools are designed around agent outcomes rather than API endpoints.

“one tool equals one agent story.”transcript, stated

`structured-output-contract` (interface-design)

Flattened arguments and enums constrain the call contract so agents do not invent complex nested objects.

“Top level primitives. These are the arguments into the function. What's the limit? What is the status? What is the email? Clearly defined.”transcript, stated

`context-compaction` (context-management)

Tool catalogs and documentation are curated because MCP handshakes consume scarce context.

“respect for the token budget really matters. It is a very scarce resource and your server is not the only one that the agent is going to talk to.”transcript, stated

Tradeoffs

Wrap workflows into one outcome tool

Chose server-side deterministic orchestration over LLM-driven orchestration of low-level API calls.

Rationale: Known workflows are cheaper, faster, and easier to debug in code.

“If you can't, there are times when you don't know the algorithm and you don't know how to write the code and it's not programmatic, that's a perfect time to use an LLM as an orchestrator.”transcript, stated

Flatten tool arguments

Chose top-level primitives and enums over nested dictionaries or object arguments.

Rationale: Flat explicit signatures reduce model and client ambiguity.

“I highly highly recommend literals or enums whenever you can. Um, much better than a string if you know what the options are.”transcript, stated

Gotchas (what bit them)

REST API mirroring creates bad agent interfaces.

Root cause: Atomic operations make the model infer workflow ordering and outcome semantics.

Resolution: Wrap known workflows into outcome-oriented MCP tools.

“just don't end up ship the REST API to prod as an MCP server. You will regret it. You will pay for it.”transcript, stated

Tool documentation can become worse than missing documentation when duplicated.

Root cause: Instructions in prompts and tool schemas drift independently.

Resolution: Keep the server/tool contract documented where the agent actually receives it.

“You have a doubly documented tool and and one is wrong and one is right and only error messages will save you.”transcript, stated

Huge tool catalogs can consume the model context before task work starts.

Root cause: MCP clients commonly download tool descriptions in one handshake.

Resolution: Curate tools and be parsimonious with schemas and descriptions.

“you would lobomize the agent on handshake because it would have no room for anything else.”transcript, stated

Evaluation

The talk evaluates MCP designs through agent usability heuristics: whether the agent can pick the right tool, stay within token budget, understand arguments, and avoid orchestration it should not perform.

Metrics: token budget consumed at handshake · tool catalog size · agent ability to choose the right tool · tool-call failure observability

“Name the tool for the agent. Don't name it for you.”transcript, stated

“observability into tool call failures.”transcript, stated

Outcomes

The guidance provides a concrete checklist for production MCP servers.
It argues for outcome-oriented tools, flat arguments, documentation as context, token budgeting, and curation.

The discussion is grounded in FastMCP/MCP ecosystem experience and enterprise examples rather than one deployed customer workload.

“these are the five major things that we talked about today in our pseudo workshop workshop that wasn't really a workshop actionable talk.”transcript, stated