Subscribe Subscribe

How to structure an MCP server so agents can actually use it

A usable MCP server is not just a wrapper around internal APIs. It needs clean tools, readable resources, and capability boundaries the model can reason about.

Many first-pass MCP servers are technically valid and practically awkward.

They expose too many vague tools, overload parameters, hide the most useful data behind write actions, and force the model to guess how the system should be used.

That defeats the point.

Start with the model's point of view

An MCP server is only useful if the model can reason about it clearly.

That means the agent should be able to understand:

  • what information it can read
  • what actions it can take
  • what each tool is for
  • when a resource is safer than a tool

If the interface is confusing to a human reviewer, it will be worse for the model.

Prefer resources for context and tools for actions

One of the cleanest patterns is:

  • resources for stable, inspectable context
  • tools for operations and side effects

Examples:

  • schema docs as resources
  • configuration snapshots as resources
  • account lookup as a tool only if it requires parameters or auth checks
  • deployment actions as tools

Do not make the model call a tool just to read something that should be a simple resource.

Keep tools narrow

A good MCP tool usually has:

  • one clear purpose
  • minimal required parameters
  • predictable output
  • a name that explains intent directly

Bad pattern:

  • one giant tool called execute_action

Better pattern:

  • list_projects
  • get_project
  • create_deploy_preview
  • restart_service

Specificity helps the model choose correctly.

Make outputs easy to reason about

The output format matters as much as the input shape.

If a tool returns a wall of mixed text, the model has to recover structure after the fact. If it returns a clean, stable shape, the model can plan more reliably.

Models perform better when the interface itself is legible.

Separate safe reads from risky writes

This matters for both usability and safety.

The model should not have to infer which tools are harmless and which ones can create side effects. Make that separation obvious in capability design, naming, and approval flow.

That reduces both mistakes and unnecessary caution.

Design for discoverability

A strong MCP server feels self-explanatory:

  • resource names are obvious
  • tool names are consistent
  • parameters are boring and direct
  • the model does not need a long custom essay to use the system correctly

If you need a huge prompt just to compensate for weak interface design, the server is not structured well enough yet.

Sources