What Is an MCP Server? (and How to Build One)

What an MCP server is

MCP (Model Context Protocol) is an open standard that connects AI agents to external tools, data and services through one common interface. An MCP server is the piece you (or a vendor) write that sits in front of a specific capability: a database, a browser, an issue tracker, a filesystem, an API. It advertises what it can do, and any MCP client can discover and use it. The reason MCP spread so fast is that it solves an N-times-M problem: before MCP, every tool needed a bespoke integration for every agent; with MCP, a tool is integrated once and works everywhere. So today there is an MCP server for almost anything you would want an agent to reach.

• A server wraps one capability (a database, a browser, an API) and exposes it to agents.
• It speaks the Model Context Protocol, so any MCP client can use it without custom glue.
• Write the integration once; every MCP-aware app benefits. This is why support spread fast.
• See the glossary entry on MCP for the short definition and tool calling for how agents invoke it.

How it works: host, client and server

MCP uses a client-server architecture built on JSON-RPC 2.0, with three participants. The host is the AI application you use, such as Claude Code or Cursor. When the host starts, it creates one MCP client for each configured server, and each client holds its own dedicated, stateful connection to one MCP server. The server is the program exposing the capability. Messages flow as JSON-RPC requests, responses and notifications over a transport. There are two transports in common use: stdio, where the host spawns the server as a local child process and they talk over standard input and output, and Streamable HTTP, used for remote, cloud-hosted servers. One host can run many client-server connections at once, which is how an agent reaches a filesystem, a browser and a database in the same session.

• Host: the AI app (Claude Code, Cursor, Claude Desktop) the user interacts with.
• Client: one per server, created by the host, holding a dedicated connection.
• Server: your program exposing a capability, speaking JSON-RPC 2.0.
• Transport: stdio for local servers, Streamable HTTP for remote ones (SSE is deprecated).

What a server exposes: tools, resources and prompts

An MCP server can expose three kinds of primitive, and a given server implements whichever ones make sense for it. Tools are actions the model can invoke, like "run this query" or "create this issue"; each tool declares an input schema so the agent knows how to call it. Resources are read-only data the agent can fetch, like a file's contents or a database record, addressed by URI. Prompts are reusable templates the server offers, often surfaced to the user as slash commands or quick actions. Tools are by far the most common, because the headline value of MCP is letting an agent act on a system, not just read it.

• Tools: actions the agent can call (query a DB, open a PR, drive a browser). Each has an input schema.
• Resources: read-only data the agent can fetch by URI (file contents, records).
• Prompts: reusable templates the server provides, often shown as slash commands.
• A server declares which primitives it supports; most lead with tools.

Build a minimal MCP server

The fastest way to understand a server is to build a tiny one. The official TypeScript SDK ships as the @modelcontextprotocol/server package and lets you stand up a working stdio server in a few lines: create an McpServer, register a tool with a name, a description and a Zod input schema, then connect it over a StdioServerTransport. The example below exposes one greet tool. Save it, point your MCP client at the command that runs it (for Claude Code, that is claude mcp add --transport stdio), and the agent can call greet. A Python SDK (FastMCP) offers the same shape if you prefer Python.

// server.ts - a minimal MCP server exposing one tool over stdio
import { McpServer } from '@modelcontextprotocol/server'
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio'
import * as z from 'zod'

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

// Register a tool: a name, a description, and a Zod input schema.
server.registerTool(
  'greet',
  {
    description: 'Greet someone by name',
    inputSchema: z.object({ name: z.string() }),
  },
  async ({ name }) => ({
    content: [{ type: 'text', text: `Hello, ${name}!` }],
  }),
)

// Connect over stdio: the host spawns this file and talks via stdin/stdout.
const transport = new StdioServerTransport()
await server.connect(transport)

Keep server.ts free of console.log on stdout: a stdio server uses stdout for the JSON-RPC protocol, so log to stderr instead. From here you add more tools, resources and prompts the same way, and switch to Streamable HTTP when you want to host the server remotely.

MCP server vs a plain API

A fair question is why an agent needs an MCP server when the underlying service already has a REST API. The difference is discovery and self-description. A REST API needs a human to read its docs and write integration code for each client; an MCP server advertises its tools, their schemas and their descriptions in a standard the agent reads at connect time, so the agent learns how to use it automatically and the same server works across every MCP client. MCP does not replace your API; it is a thin, agent-friendly layer in front of it. For internal one-offs, a CLI the agent can call may be simpler, but for anything you want many agents and apps to use, an MCP server is the interoperable choice.

• A REST API needs per-client integration code; an MCP server is self-describing and reused everywhere.
• The agent reads tool schemas and descriptions at connect time, so it knows how to call them.
• MCP sits in front of your API as an agent-friendly layer, it does not replace it.
• For a private one-off, a CLI may be simpler; for shared use, a server wins.

Common servers worth knowing

You rarely have to build a server from scratch, because the ecosystem already covers the common cases. Good first connections are the filesystem server (scoped to a folder so the agent can read and write project files), the Playwright server (so the agent can drive a real browser to test or scrape), and a database server for your stack. Beyond those, there are servers for issue trackers, design tools, monitoring and most major SaaS products. Connect deliberately, though: every server adds its tool definitions to the agent context, so each one has an ongoing cost, and a server is third-party code with access to your systems, so vet it like any dependency. Our Claude Code MCP setup guide walks through adding, scoping and verifying servers safely.

• Filesystem server: read and write files in a scoped folder.
• Playwright server: let the agent drive a real browser.
• Database server: query your data directly instead of pasting rows into chat.
• Connect few and vet each: every server costs context and is third-party code.

Step by step

1. 01

   Install the SDK

   In a new Node.js project, install the official TypeScript SDK with "npm install @modelcontextprotocol/server" (and zod for input schemas). A Python SDK, FastMCP, is available if you prefer Python.

2. 02

   Create the server and register a tool

   Create an McpServer with a name and version, then call server.registerTool with a tool name, a description and a Zod inputSchema, returning a content array from the async handler.

3. 03

   Connect over a transport

   For local use, create a StdioServerTransport and await server.connect(transport). The host spawns your file and talks to it over stdin/stdout, so log to stderr, never stdout.

4. 04

   Register the server with a client

   Point your MCP client at the command that runs the server. In Claude Code: "claude mcp add --transport stdio <name> -- node server.js". See our Claude Code MCP setup guide for scopes and verification.

5. 05

   Verify and extend

   Confirm the agent can see and call your tool, then add more tools, resources and prompts the same way. Switch to Streamable HTTP when you want to host the server remotely.

Frequently asked questions

Keep learning