Guides

Building your first MCP server: what to know before you start

aaaa.fyi · 2026-07-10 · 7 min read

An MCP server is smaller than you think: a process that declares a list of tools and answers typed calls to them. The official SDKs (TypeScript and Python) handle the protocol; you write the functions.

The three primitives

Tools — actions the agent can take. Each has a name, a description and a JSON schema for inputs. This is 90% of most servers.

Resources — read-only data the agent can load, like files or API responses.

Prompts — reusable prompt templates the server exposes.

Decisions that matter

Write tool descriptions for the model, not for humans. The agent picks tools by reading descriptions. Vague descriptions produce wrong tool calls; specific ones ("Search issues by label and state, returns at most 30") produce reliable behavior.

Return errors as data. An agent can recover from {"error": "branch not found"}; it cannot recover from a crashed server.

Keep the tool count low. Twenty focused tools beat eighty thin wrappers — every extra tool competes for the model's attention.

Study the winners

Before designing your API, read the source of the most-installed servers. The patterns that survive contact with real agents — snapshot-based browser control, scoped database access — are all visible in their tool definitions.