Building MCP Servers That Agents Can Actually Use — and Trust

We connected a remote MCP server to an agent in about five minutes. It worked on the first try — the agent listed the tools, called one, came back with the right answer. Everyone was pleased until a teammate asked the only question that mattered: “What can this thing actually do, and to what — our staging data or production?” Nobody in the room knew. We'd confused connected with safe, and it answered with it was tested. This post is about closing both gaps.

There's a good post already on this site about the protocol itself — the n×m math, the JSON-RPC handshake, the confused-deputy attack — in the MCP production playbook. I won't re-litigate that here. This one is the builder's companion: how to design a server agents use well, how to expose a remote one without regret, and the concrete steps to connect and test it inside an AgentSwarms agent. Less theory, more “what do I actually type and click.”

What you're actually building

An MCP server is a small, standardized adapter that sits in front of capabilities you already have. It exposes three kinds of things, and most servers only ever use the first:

The protocol underneath is JSON-RPC: the client initializes, asks the server to list its tools, then calls them with typed arguments. If you want to watch that conversation step by step, the playbook has an animated version — here's the short one:

Designing tools an agent can actually use

This is the part that separates a server that demos well from one that works in the hands of a model you don't control. A tool isn't an API endpoint with a fancy hat — it's an instruction you're giving to a reasoning system that will read your description literally and call you with whatever it inferred. Sloppy tools produce sloppy agents. Compare the same tool written two ways:

• Name tools like verbs, scope them like nouns — refund_order, not doStuff or handler3. The agent picks tools by name and description; vague names get mis-selected.
• The description is a prompt — write it for the model, not for your API docs. State what it does, what it returns, and when not to use it. One good sentence prevents a dozen wrong calls.
• Type every argument and validate server-side before you touch anything real. The model will eventually pass you a string where you wanted an int; decide how that fails on purpose.
• Return structured errors, not stack traces — { "error": "order_not_found" } is something an agent can reason about and recover from. A 500 with a traceback is something it will hallucinate around.
• Make writes idempotent — agents retry. A refund_order that issues two refunds because the first response timed out is a tool that will cost you money. Take an idempotency key.
• Mark risk explicitly — read-only tools and destructive tools should not look the same to the system that gates them.

In practice the SDK makes the protocol disappear, so almost all your effort goes into the contract above. A production-shaped tool looks like this — note how much of it is guarding, not doing:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("orders")

@mcp.tool()
def refund_order(order_id: str, reason: str, idempotency_key: str) -> dict:
    """Issue a refund for an order. HIGH RISK — writes money.
    Use only after confirming the order exists and is refundable.
    Returns {status, refund_id} or {error}."""
    require_scope("orders:refund")                 # authorization, per-action
    if not (order := db.fetch_order(order_id)):    # validate before acting
        return {"error": "order_not_found"}         # structured, recoverable
    if seen(idempotency_key):                       # retries are safe
        return cached(idempotency_key)
    result = payments.refund(order_id, reason)
    audit.log("refund_order", order_id, result)     # who/what/when, immutably
    return store(idempotency_key, result)

Build local, then go remote — deliberately

Every MCP server starts its life talking over stdio — a pipe to a process on your own machine. That's the right place to build and do your first tests: it's sandboxed by the OS, there's no network, and the stakes are low. The moment you move to a remote server reachable over HTTP/SSE, you've crossed a trust boundary, and a whole category of obligations switches on:

Exposing a remote server without regret

Here's the layered checklist I won't skip before pointing an agent at a remote server. Click each layer to add it and watch the gauge — the point is that these aren't a menu you pick from, they're a stack you complete:

The failure mode all of this defends against has a name — the confused deputy. Your server holds powerful credentials; an instruction smuggled into the agent's input tricks it into using those credentials for the attacker. The fix is scoped, consent-gated access instead of one over-powered token:

Connecting and testing it in AgentSwarms

Once your server is exposed, you need to actually use it from an agent and confirm it behaves. This is where AgentSwarms turns the abstract into four concrete steps you can do right now:

1. 1Connect the server under /mcp (“MCP Integrations”). Give it a name and type, paste the endpoint (an sse://… URL or a stdio://… command), and pick auth: none, a bearer token, or OAuth.
2. 2Let it probe. On connect, AgentSwarms probes the server and discovers the tools it exposes — you'll see a live tool count and the tool list on the server card. If the probe fails, you find out here, not mid-conversation with a user.
3. 3Allow-list it on an agent. In the Agent Builder, enable the MCP Tool, then tick exactly which connected servers that agent may call. Leave it empty and the agent can reach any connected server — usually not what you want.
4. 4Test in the Playground. Chat with the agent, watch it invoke the remote tools, and open the trace to see every call: which tool, what arguments, what came back. That trace is your proof it did what you think.

Scope every agent to the smallest set of servers

The allow-list is the single most important control on this page, and it's easy to leave wide open. An agent that only needs to look up orders should not be able to reach your internal database server just because both are connected to the workspace. Toggle the servers an agent may call:

MCP is becoming plumbing — boring, ubiquitous, load-bearing, the way HTTP is. The teams that win with it won't be the ones who connected a server fastest; they'll be the ones whose servers are well-designed, scoped, audited, and tested against a real agent in a real trace. Build the server like a model will read every word of it, expose it like the internet will probe it, and test it like a user's data is on the line — because eventually, all three are true.