How to Build an MCP Server: A Practical Guide

The Model Context Protocol specification and the official SDK repositories are the two primary sources for everything in this article. The spec (revised July 28, 2026) defines the protocol; the SDKs implement it. We link to both throughout, and every claim here traces back to one or the other.

What an MCP server does

The MCP specification defines a server as a process that exposes three kinds of primitives to clients. Each primitive has its own discovery and invocation methods:

• Tools are executable functions. A tool has a name, a description, and an inputSchema defined in JSON Schema. Clients discover tools via tools/list and invoke them via tools/call, passing arguments that match the schema. Tools are the primary way an MCP server performs actions: querying a database, calling an API, running a calculation.
• Resources are data sources. They provide context to the client without performing side effects. Clients call resources/list to discover what is available and resources/read to retrieve content. Resources are how a server exposes files, database records, or live data feeds.
• Prompts are reusable templates that guide interactions. They let a server define structured ways for clients to request specific behaviors, such as a code review template or a data analysis workflow.

For a deeper explanation of the protocol itself, see our MCP guide and the glossary entry on Model Context Protocol.

The architecture

MCP uses a three-layer architecture: host, client, and server. The host is the application the user interacts with, such as Claude Desktop, VS Code, or Cursor. The host creates one or more MCP clients, and each client maintains a one-to-one connection with a single MCP server. The server does the actual work: exposing tools, resources, and prompts over the connection.

All communication uses JSON-RPC 2.0. The client sends a JSON-RPC request (such as tools/call with the tool name and arguments), the server processes it, and returns a JSON-RPC response. Servers can also push notifications to clients, but only when clients have opted in via subscriptions/listen.

This separation matters because it means a single host can connect to many servers simultaneously. Claude Desktop, for instance, can connect to a filesystem server, a database server, and a custom business-logic server at the same time, each running independently.

Choose your SDK

The MCP project maintains two official SDKs. Both implement the full protocol and provide a Server class for registering tools, resources, and prompts.

For most projects, the choice comes down to your existing stack. If the data and logic you want to expose already live in Python, use the Python SDK. If your stack is Node or TypeScript, use that one. The protocol is the same either way.

Define your tools

A tool in MCP has three parts: a name, a natural-language description, and an inputSchema written in JSON Schema. The description tells the AI model what the tool does and when to use it. The input schema defines exactly what arguments the tool accepts, their types, and which are required. When a client calls tools/list, the server returns this metadata for every registered tool.

When the AI model decides to use a tool, the client sends a tools/call request with the tool name and a JSON object of arguments. The server validates the arguments against the schema, executes the function, and returns the result.

The Python SDK’s FastMCP API lets you register tools using a decorator on a regular function, with Python type hints automatically converted to the JSON Schema. The TypeScript SDK uses a method call where you pass the name, schema object, and handler function. Both approaches are documented in the respective SDK repositories at github.com/modelcontextprotocol.

Add resources and prompts

Resources let your server expose data without side effects. A resource has a URI, a name, and a MIME type. Clients discover resources via resources/list and fetch them via resources/read. Common uses include serving file contents, database query results, or configuration data that gives the AI model context it needs to make good tool calls.

Prompts are reusable interaction templates. They have a name, a description, and optionally a set of arguments. When a client requests a prompt, the server returns a structured message sequence the AI model can use. This is useful for standardizing workflows like code review, data analysis, or report generation, where you want the model to follow a consistent pattern.

Both resources and prompts are registered through the same Server class used for tools. The SDKs provide parallel registration patterns: decorators in Python, method calls in TypeScript. The specification documents the full lifecycle for each primitive.

Configure transport

The MCP spec defines two transports, and the choice determines how your server connects to clients:

• Stdio is the local transport. The host launches the server as a child process. Communication flows over standard input and output. There is no networking, no ports, no TLS. This is the simplest path for local development and for connecting to desktop hosts like Claude Desktop.
• Streamable HTTP is the remote transport. The server runs as an HTTP service, and the client connects over the network. Server-sent events (SSE) handle streaming responses. This is the right transport when the server runs on a different machine, in a container, or needs to serve multiple clients.

Both transports carry the same JSON-RPC 2.0 messages. You can develop with stdio locally and switch to Streamable HTTP for deployment without changing your tool, resource, or prompt definitions. The SDKs handle the transport layer, so the application code stays the same.

Test with MCP Inspector

The MCP project publishes the MCP Inspector, a dedicated testing tool for MCP servers. It connects to your server, calls tools/list, resources/list, and prompts/list to enumerate everything the server exposes, and provides an interface for invoking tools and reading resources interactively.

Use the Inspector before connecting your server to a production host. It catches schema errors, missing descriptions, and transport issues in isolation, without the complexity of a full AI conversation. Once your tools list cleanly and return correct results in the Inspector, you can be confident the server will behave correctly when connected to Claude Desktop, VS Code, or any other MCP host.

Connect to a host

An MCP server is only useful when connected to a host. The hosts that currently support MCP include Claude Desktop, VS Code (via the Copilot extension), and Cursor. Each host has its own configuration format for registering servers, but the pattern is the same: you specify the server’s transport (stdio command or HTTP endpoint), and the host creates a client that connects to it.

For stdio servers, this typically means adding an entry to a JSON configuration file that tells the host which command to run. For Streamable HTTP servers, you provide the URL. The host then calls server/discover to learn what the server offers and makes its tools, resources, and prompts available within the AI conversation.

The reference server repository includes working implementations for common integrations: filesystem access, PostgreSQL, GitHub, Slack, and Google Drive, among others. These serve as both useful tools and reference implementations for building your own.

Security checklist

The MCP specification is explicit about security requirements. These are not suggestions; they are documented requirements for spec-compliant implementations:

1. User consent for tool execution. Users must explicitly approve tool calls. The spec does not permit silent, automatic execution of tools on behalf of a user without their knowledge.
2. Untrusted tool descriptions. Tool descriptions should be treated as untrusted input unless the server is known and trusted. A malicious server could provide descriptions designed to manipulate the AI model’s behavior.
3. Data privacy and consent. Hosts must obtain user consent before exposing user data to MCP servers. A server that reads files or accesses databases should not silently exfiltrate data the user did not intend to share.
4. Authorization flows. Implement robust authorization, especially for Streamable HTTP servers accessible over a network. The spec recommends proper authentication and access control rather than relying on obscurity.
5. Input validation. Validate all arguments against the declared JSON Schema before execution. The schema is the contract; enforcing it prevents injection and unexpected behavior.

Security for AI agent systems requires attention at every layer. Our AI agent development practice builds these controls into every MCP integration from the start.

When to hire help

Building a basic MCP server that wraps one API is straightforward with the SDKs. The complexity grows when you need production-grade reliability: robust error handling, authentication for remote transports, rate limiting, monitoring, and the security controls the spec requires. It grows further when the server is part of a larger AI agent system with multiple tools, orchestration logic, and real user data.

Webvello builds custom MCP servers and AI agent systems as part of our AI agent development and Claude Code development services. If you need an MCP integration that handles real workloads, we can scope and build it. The schema generator is also a useful starting point for defining tool input schemas before writing server code.

Frequently asked questions

About the work

Webvello is an AI search optimization and AI agent development company founded in 2024, based in Roseville, California. We build MCP integrations, Claude Code workflows, and AI-powered tools for businesses that need their systems to talk to large language models reliably. Founder George Shvaya came to this work from cybersecurity and systems engineering, which is why this article reads the protocol specification rather than paraphrasing blog posts. Our AI Search Playbook covers the broader program.

Sources: the Model Context Protocol specification at modelcontextprotocol.io (revised July 28, 2026), the official SDK repositories at github.com/modelcontextprotocol, and the Anthropic developer documentation at docs.anthropic.com. All links verified November 3, 2026. The specification may change; check the linked pages before relying on a detail.