MCP server primer.

The term MCP serverstarted appearing in release notes, tutorials, and VC Twitter threads sometime in early 2025. Twelve months later it's a weekly topic, and most explanations still land in one of two unhelpful places: too abstract ("universal protocol for AI integrations") or too technical ("JSON-RPC 2.0 with capability negotiation over a stdio transport"). Neither tells you what's on the other end of the connection or why you'd care. This is the version I wish I'd read first.

What an MCP server actually is

An MCP server is a small program you install locally that exposes tools to a language-model client. A tool is anything the model can call by name with structured arguments: read_file, query_database, count_tokens, send_email. When you're chatting with Claude and it says "let me check the file system," what's actually happening is that the client (Claude Desktop) is invoking a tool on a local MCP server (filesystem) and handing the result back to the model.

The server doesn't talk to the model directly. It talks to the client— the app you're using (Claude Desktop, Cursor, Zed) — which handles all the LLM communication. Your server reads JSON-RPC messages off stdin, does whatever it needs to, and writes responses back to stdout. That's the whole contract.

Why Anthropic shipped a protocol for this

Before MCP, every LLM-tool integration was bespoke. You wanted Claude to read your Notion pages? You wrote a Notion adapter into your Claude-powered app, parsed tool-call outputs, handled retries, and shipped it. Ten apps wanting Notion = ten adapters. Ten apps wanting ten different data sources = a hundred integrations, all roughly doing the same thing.

MCP flips that. Notion (or a third party) ships one MCP server. Any MCP-compatible client gets Notion integration for free. It's a shift from M×N integrations to M+N. The analogy Anthropic used in the launch materials was USB-C — one physical connector that ends the dongle war. Same basic idea at the software layer.

How to use an MCP server with Claude Desktop

The process for installing an MCP server in Claude Desktop is three commands and a config edit. Here's the short version using our token-counter server as the example.

1. Install the server — anywhere on your machine:

   npx briskly-mcp-llm-token-counter

   This downloads and runs the server once. You don't actually need to do anything with this session — you just need the package cached so Claude Desktop can spawn it.

2. Edit the Claude Desktop config — at %APPDATA%/Claude/claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS. Create the file if it doesn't exist:

   {
     "mcpServers": {
       "token-counter": {
         "command": "npx",
         "args": ["briskly-mcp-llm-token-counter"]
       }
     }
   }

3. Quit Claude Desktop fully and relaunch. Not the window — the whole app, including the menu-bar process on macOS or the tray icon on Windows. On restart, the server's tools show up under the plug icon in the chat input. You can ask something like "how many tokens is this paragraph in GPT-4o?" and the model will invoke count_tokens under the hood.

That's it. Cursor and Zed have similar config files in their own settings UI. Most MCP servers you'll install follow the same pattern: one config block per server, launch command plus args, restart the client.

What you can do with one

Some real examples of MCP servers in use today, roughly sorted by how often they're installed:

• Filesystem — scoped read/write to a directory. The model can open, search, and edit files inside the scope. Most common entry point for people trying MCP for the first time.
• GitHub — list repos, read issues, open pull requests. Good replacement for pasting URLs into chat.
• Database (Postgres, SQLite, MySQL) — schema introspection plus read-only queries. Turns the model into a competent SQL-writing assistant on your real tables.
• Slack / Notion / Linear — read context from wherever your work actually lives, so you don't have to paste 30 messages into the prompt.
• Domain-specific utilities — token counters, cost estimators, image resizers, formatters, linters. These are the long tail. Useful if they match your workflow, invisible otherwise.

Building your own in an afternoon

The official TypeScript SDK is @modelcontextprotocol/sdk. Install it, import the Server class, register a ListToolsRequestSchema handler that returns your tool definitions, register a CallToolRequestSchema handler that runs them, and wire the server to a StdioServerTransport. That's the whole architecture. A working server is about 50 lines of TypeScript including the type boilerplate.

The actual work is in the tools — the functions your server exposes. A token counter wraps gpt-tokenizer. A Postgres server wraps the pg client. A GitHub server wraps Octokit. The MCP layer isn't doing anything clever; it's just the introduction system between the model and the code you already know how to write.

Ship by publishing to npm with npm publish --access public and pointing your bin field in package.json at your compiled entry point. Users install it via npx and wire it into their Claude config in two minutes. For discovery, submit to the smithery.ai registry (the de facto MCP directory right now).

MCP server vs. other integration patterns

Quick distinctions that come up when people first hit MCP:

• vs. plain API: A REST API is something your code calls. An MCP server is something the model calls on your behalf through the client. MCP removes the custom tool-calling loop.
• vs. ChatGPT plugins: Plugins were OpenAI-specific, hosted on remote web services, and invoked via an OpenAPI manifest. MCP is vendor-neutral, typically local, and uses its own schema. Plugins were deprecated; MCP has absorbed the use cases.
• vs. function calling: Function calling is a model capability — you give the model a tool schema in the prompt, it emits a structured tool call, you parse and execute. MCP is a delivery mechanism for those tools: the schemas come from the server, the client does the parsing, you just expose the capability.
• vs. agents: An agent is a pattern where a model loops over tool calls autonomously. MCP is what the agent calls into. Claude's Managed Agents product, for instance, can consume MCP servers as one of its tool sources.

Limitations and gotchas

• Trust is on you. An MCP server runs with your user permissions. The model decides when to invoke it. A server with a shell-execute tool, invoked from a malicious prompt hidden in a document the model read, can do real damage. Stick to official or widely-reviewed sources and prefer narrow-scope tools.
• Stdio servers are per-client-session. Each client spawns its own subprocess. Expensive startup (huge model loads, database warmups) happens every launch. For hot-path cases, either use HTTP transport or cache on first call.
• Discovery is rough. There's no single registry everyone uses. Smithery is the most-complete; GitHub topic tags are patchy; the official list at modelcontextprotocol.io is curated but shorter. Expect to spend real time finding the server you actually need.
• Schema-on-read problems still exist. The model sees your tool descriptions, not your implementation. Vague descriptions get vague tool calls. If your server has a query tool described as "runs SQL," expect mediocre results. Tool descriptions are prompt engineering for your future self.

FAQ