5 things that break your MCP server (and how to fix them)

I've built MCP servers in production: a file system tool, a REST API wrapper, a PostgreSQL reader, a multi-tool agent. Each one hit at least one of these failures during development. Here are the five that come up most, and the specific fixes for each.

1 Your tool schema doesn't match what the model actually sends

The model reads your tool description and infers what to pass. If your schema says a parameter is a string but your description implies it could be a number, the model will sometimes send a number. Your Zod validation catches it, returns an error, and the model hallucinates a fix or gives up.

The root cause is treating schema and description as independent. They're not. The model uses both together to decide what to send.

const schema = z.object({
  query: z.string().describe("The search query as a plain string"),
  limit: z.number().int().min(1).max(100)
    .optional()
    .describe("Optional. Max results to return. Defaults to 10."),
});

2 Errors return as plain strings instead of MCP error format

When your tool throws, the MCP client needs a properly formatted error response. If you just throw or return a plain string, some clients will display nothing, some will crash, and some will retry indefinitely. The model sees an ambiguous response and either hallucinates success or stops dead.

try {
  const result = await doSomething(input);
  return {
    content: [{ type: "text", text: JSON.stringify(result) }],
  };
} catch (err) {
  return {
    content: [{
      type: "text",
      text: `Error: ${err instanceof Error ? err.message : String(err)}`,
    }],
    isError: true,
  };
}

3 stdio transport breaks when you log to console

If you're using stdio transport (the default for Claude Desktop), any console.log you add for debugging goes to stdout. The MCP client reads stdout as JSON-RPC messages. A stray log line corrupts the message stream and the whole server stops responding.

// Safe: goes to stderr
console.error("[debug] fetching resource:", url);

// Or write to file
import { appendFileSync } from "fs";
const log = (msg: string) =>
  appendFileSync("/tmp/mcp-debug.log", `${new Date().toISOString()} ${msg}\n`);

4 Your tool does too many things

A tool named manage_database that can query, insert, update, and delete is hard for the model to use correctly. The model has to infer which operation you want from the description, and it gets it wrong often enough to be a real problem. You also end up with a schema that has 12 optional parameters that interact in non-obvious ways.

5 No timeout on external calls

Your tool calls an external API. The API hangs. The model waits. After 30 seconds it either gives up or retries. Either way the user sees nothing useful and you don't know what happened.

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 8000);

try {
  const res = await fetch(url, { signal: controller.signal });
  clearTimeout(timeout);
  return await res.json();
} catch (err) {
  clearTimeout(timeout);
  if (err instanceof Error && err.name === "AbortError") {
    throw new Error(`Request to ${url} timed out after 8 seconds`);
  }
  throw err;
}

These five cover the failures that come up in almost every first MCP server. There are more (auth patterns, resource vs tool decisions, schema versioning, SSE vs stdio tradeoffs) but fix these five first.