MCP Server Builder

An MCP server is how Claude reaches a system it does not otherwise know about — your database, your internal API, your ops tooling. The protocol is small. Almost every real problem is a design problem: which tools to expose and what they return.

Decide the Shape First

Local (stdio) — runs on the user's machine, launched by the client, credentials from the local environment. Right for developer tooling and anything touching localhost or a local database. Only that machine gets it.

Remote (HTTP) — deployed once, reached by URL, OAuth for identity. Right when a team needs it, or when the data lives in a service rather than on a laptop. Everyone gets updates the moment you deploy.

Build remote when more than one person will use it. Retrofitting local-only to multi-user later means redoing auth from scratch.

Tool Design — the part that matters

Tools are an interface for a model, not a REST API. The common failure is exposing twenty thin endpoint wrappers and watching the model chain them badly.

Name the job, not the endpoint. get_pipeline_board beats query_deals plus query_stages plus query_owners.
One call should answer a real question. If using your server always takes three calls in the same order, that sequence should have been one tool.
Descriptions are prompts. Say what the tool is for, when to reach for it, and what it does not do. This text is the only instruction the model gets.
Return prose-shaped, compact results. Trim nulls and internal ids nobody will use. A 40KB JSON blob buries the answer and eats the window.
Paginate and cap. Always a default limit. Say in the response when results were truncated, and how to get the rest.
Separate reads from writes. Writes get explicit, narrow tools with clear names — never a generic execute that takes arbitrary input.
Errors are instructions. "No company matched 'acme' — try search_companies first" gets recovered from; "500 Internal Server Error" does not.

Ten well-shaped tools beat fifty thin ones.

Minimum Viable Server

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { z } from 'zod'

const server = new McpServer({ name: 'acme-crm', version: '1.0.0' })

server.tool(
  'get_deal',
  'Fetch one deal with its owner, stage, and recent activity. Use when the user names a specific deal or company.',
  { id: z.string().describe('Deal id or display id like D-1042') },
  async ({ id }) => ({ content: [{ type: 'text', text: await renderDeal(id) }] }),
)

await server.connect(new StdioServerTransport())

Check the SDK's current API before writing more than this — the interface has changed across releases, and code written from memory tends to target an older one.

Security

Least privilege on the credential. A read-only token for a read-only server.
Never take a raw query string from the model into a database. Parameterize, allow-list tables, scope by tenant on the server side.
Scope every request to the authenticated user. A remote server that trusts a user id in the arguments is an authorization hole.
Never log or return secrets. Redact tokens in error paths.
Rate-limit writes.

Debugging

npx @modelcontextprotocol/inspector node build/index.js   # exercise tools directly
claude mcp list                                           # is it registered
claude mcp get <name>                                     # config and status

Tools missing in the client is nearly always one of: the server crashed on startup (run it by hand and read stderr), a stdio server wrote a stray console.log to stdout and corrupted the protocol stream, the config points at a stale build, or the client was not restarted. For stdio servers, all logging goes to stderr — stdout belongs to the protocol.

Ship Checklist

Every tool description says when to use it and when not to.
Every tool tested through the inspector, not only through the client.
Results capped and truncation stated.
Errors say what to try next.
Credentials from the environment, never in the repo.
README: install, config snippet, and one example prompt per tool.

mcp-server-builder