MCP Servers: Why Most Fail And What Works

The protocol gives you a clean way to expose tools (functions the AI can call), resources (files or data the AI can read), and prompts (templates the user can invoke). That's the contract. Everything beyond that is your decision as the server author, and most of those decisions are made the wrong way the first time.

A typical failure mode: a developer wraps an existing REST API one-to-one, exposes 47 endpoints as 47 tools, names them after the API path, and calls it done. The AI then sits in front of 47 vaguely-named functions, picks the wrong one half the time, gets back JSON it can't parse cleanly, and the user concludes 'AI integrations don't work'.

The fix is editorial - the same skill set as good API design or good function naming, applied to the AI-facing surface specifically.

1. Narrow, well-named tools. Instead of exposing get_user, get_user_by_email, get_user_by_id, get_user_with_orders as four separate tools, expose one find_user tool that takes a flexible input. Fewer tools, each doing more, with names a non-developer would understand. The AI picks faster and gets it right more often.

2. Right-sized responses. A tool that returns 50 KB of JSON when the user asked for a single field burns context window for no benefit and often gets truncated. Return what was asked for, and offer a follow-up tool for the full payload when needed.

3. Unambiguous descriptions. The tool description is the only thing the AI sees when deciding which to use. 'Search for things' tells the model nothing. 'Search the customer database by name, email, or phone number; returns at most 10 matches with id, name, and email' is what works.

4. Auth handled out of band. If your server requires OAuth, complete it once at install time and store the token. Asking the AI to bounce the user through an authentication dance mid-conversation breaks the flow every time. The user-experience cost is enormous.

5. Useful error messages. When something fails, return a string the model can reason about - 'no customer found with that email' or 'rate limit hit, retry in 60 seconds' - not a 500 with a stack trace. The model uses error messages to decide what to do next; cryptic ones produce silent failures.

The five points above are easier to believe with a real server in front of you. Docusign, the e-signature company, has published an engineering write-up, How We Made the Docusign MCP Server Production-Ready, describing how a hackathon prototype became a product. According to that post, it went into closed beta with Claude in February 2026 and reached general availability on 30 September 2026, with connectors for Claude, ChatGPT, Gemini, Microsoft Copilot, Slackbot and Perplexity. Docusign says thousands of users have made millions of tool calls through those integrations. Its own conclusion is the one this article opens with: connecting the model to the tools was the easy part.

Three lessons from it carry over to almost any server, whatever it connects to.

One server, many AI clients

When the same server answers Claude, ChatGPT and Copilot, you can't tune it for one model's quirks. Each client (the chat app that calls your server) picks tools differently, so the server has to make the right path obvious on its own. Docusign's answer to a vague request like 'send this for signature' is a routing tool, resolveEnvelopeSendMethod, which returns the three ways a document could be sent - an existing template, an uploaded file or a URL - so the model asks the user which one they mean instead of guessing. That is point 3 above, tool descriptions that remove ambiguity, taken one step further: when the request itself is ambiguous, build a tool whose whole job is to surface the question.

Consent for actions that can't be undone

Sending a contract for signature has legal weight, so 'the model probably meant this' isn't good enough. Docusign handles the high-stakes path with MCP Apps - a small interactive form rendered inside the chat - that walks the user through adding documents, recipients and signing order, and a message before anything is sent. The model gathers the details; the person confirms them. Admin control sits on the server too: Docusign says an organisation can switch MCP access on or off for its users at any time, and because that is enforced server-side it applies across every connected client at once. The transferable rule: put irreversible actions behind an explicit human step, and enforce permissions in the server rather than trusting each client to do it.

Keeping tool calls reliable as things change

Models update, clients update and your own API changes, so a server that worked last month can quietly break. Docusign runs automated evals (scripted test conversations with checked outcomes) built on the open-source Promptfoo framework. Each test checks that the expected tools were called in order, that no tool outside the allowed set was used, that the run stayed within a step budget, and - using a grader from a different model family - that the answer matches what the API actually returned. The suite runs on every change and on a schedule against production to catch drift, and it includes security cases such as prompt injection (instructions hidden in a document's text that try to hijack the model). The post gives one example the suite caught: the agent summarised cancelling a workflow without ever calling the cancel tool. It also reports that a regression cycle which took about 80 hours of manual testing now takes under two.

That last failure is worth dwelling on, because it is the one users never see: a confident answer with no action behind it. If you're choosing a test harness, our comparison of LLM eval frameworks covers the options, and building AI agents that survive production covers the wider operational picture.

If you're building an MCP server and the AI experience is patchy, audit the five points above before blaming the protocol or the model. Most MCP server failures trace to design decisions in the integration layer that would be obvious problems in any API - they're just amplified because the consumer is a probabilistic system rather than a human reading the docs.

If you're evaluating MCP servers as a user - inspect the tool list before you trust the integration. A server exposing 20+ generically-named tools with thin descriptions will struggle with any non-trivial task; a server exposing 5 focused tools with good descriptions usually shines.