Building your first MCP server: five decisions that slow you down

The TypeScript isn't the hard part. MCP's SDK is well-documented and the basic server skeleton takes maybe 20 minutes to get running. What takes hours is five architectural decisions you have to make with almost no guidance.

1. Tools vs. resources vs. prompts

MCP gives you three primitives: tools (the model calls them to take actions), resources (the model reads them for context), and prompts (templates the model can use). Most tutorials start with tools and never explain when to use the others.

The heuristic I use: if the model needs to do something, it's a tool. If it needs to read something, it's a resource. Resources work better than tools for things like configuration files, schema definitions, and static reference data — the model can load them once and reference them throughout a session without making repeated function calls.

Most people implement everything as tools because that's what the examples show. You end up with a getConfig() tool that the model calls every time it needs a config value, when a resource that loads the config once would be faster and cleaner.

2. Error handling that the model can use

When a tool call fails, you have two options: throw an error (which surfaces as an exception to the model) or return an error object (which the model can read and act on).

Most first implementations throw. That works but it's crude — the model sees "tool call failed" and doesn't have much to work with. Returning a structured error lets the model handle it gracefully:

// Instead of:
throw new Error("File not found: " + path);

// Return:
return {
  success: false,
  error: "file_not_found",
  path: path,
  suggestion: "Check that the path is relative to the project root"
};

The model reads the suggestion and tries the right path. Without it, it guesses.

3. Authentication scope

Does your server need auth? If it's wrapping an internal API or touching user data, yes. How you handle it matters for security and for the developer experience of anyone using your server.

The common mistake is putting credentials in the tool call itself — the model passes an API key as a parameter. That means the key shows up in conversation history, logs, and any context the model stores. Better to load credentials from environment variables at server startup and never pass them through the model at all.

4. Stateless vs. session state

By default, MCP tools are stateless — each call is independent. That's fine for most things. But some tools are more useful with state: a file navigation tool that remembers where you are, a search tool that keeps the last query context, an agent that accumulates findings across multiple calls.

Adding session state means adding complexity. You need to decide where state lives (in-memory vs. persisted), how it gets scoped (per-conversation, per-user, per-session), and what happens when it gets stale. Most first MCP servers don't need this. The time you spend building it is time you're not building the actual tool functionality.

Start stateless. Add state only when a real usage pattern requires it.

5. What goes in the tool description

The tool description is what the model reads to decide whether and how to call your tool. Most first implementations write descriptions for humans ("This tool reads a file") rather than for the model ("Use this to read the contents of a specific file. Requires an absolute path. Returns the file contents as a string, or an error if the file doesn't exist.").

The model uses your description to construct the arguments. Vague descriptions produce bad arguments. Specific descriptions produce correct ones. Include: what the tool does, when to use it vs. alternatives, what valid inputs look like, and what the output format is.

This is the one decision with the most direct impact on tool call quality, and it's the one that gets the least attention in tutorials.

---