Model Context Protocol (MCP) servers are services that expose tools, resources, and prompts in a standard way so AI agents can call them safely and consistently. Instead of building one-off integrations for every agent × data source combination, MCP provides a shared interface that keeps auth, data formatting, and error handling predictable across systems.
This guide demonstrates how to build an MCP server step by step, including how to define capabilities, handle errors, and apply basic security patterns.
TL;DR MCP servers expose tools, resources, and prompts through a standardized interface so AI agents can access them consistently. Build custom servers when pre-built options cannot access your internal systems, meet compliance requirements, or encode company-specific business logic.Servers expose three capability types: tools for executable actions, resources for read-only data, and prompts for reusable templates. The SDK handles protocol details while you define what your server can do through simple decorators or function calls. Use STDIO transport for local development and Streamable HTTP for production deployments. Test with MCP Inspector before connecting to Claude Desktop, and return errors as tool results with actionable guidance for agents. Security requires authentication, input validation, and least-privilege access from day one. Validate all inputs, restrict file system access to allowed directories, and load credentials from environment variables rather than code. We’re building the future of agent data infrastructure.
Get access to Airbyte’s Agent Engine.
Try Airbyte Agents →
Why Build a Custom MCP Server? Build a custom MCP server when pre-built servers cannot access your internal systems.
Internal data warehouses are the most common reason. Custom schemas, organization-specific query patterns, and strict access controls rarely work with generic MCP servers. If your data lives behind internal auth or requires custom logic, you need to build.
Security and compliance are the second driver. Teams in regulated environments often require on-prem deployment, full audit trails, and complete visibility into how agents access data. Pre-built servers cannot meet these constraints.
Custom business logic is the final case. If your agent encodes multi-step workflows that reflect how your company operates, building makes sense. Use the “buy to learn, build to differentiate” rule: rely on pre-built servers for standard tools like GitHub or PostgreSQL , and build custom servers only for systems unique to your business.
What Do You Need Before Building? Before building an MCP server, you need the following:
Python 3.10 or higher : Required because the MCP SDK depends on modern Python language features. The official documentation recommends using uv for project management, though pip works for simpler setups.MCP Python SDK : Install with pip install "mcp[cli]" or uv add "mcp[cli]". The official SDK includes FastMCP, a high-level framework that handles protocol details automatically. Import it as from mcp.server.fastmcp import FastMCP. Use the lower-level mcp.server APIs only if you need direct protocol control.A testing host for LLM interaction : Use Claude for Desktop as your primary MCP host to validate behavior before production. For local development and debugging, run the MCP Inspector via uv run mcp dev server.py to inspect tools, resources, prompts, and server behavior without configuring a full client.Once your environment is set up, define what your MCP server exposes before writing code. Use @mcp.tool() for executable actions, @mcp.resource() for data access, and @mcp.prompt() for reusable templates. Each capability must declare clear type annotations and schemas so agents can understand how to use it.
Match capabilities to MCP primitives consistently. Tools execute logic, resources expose data, and prompts define structured templates. All schemas are registered at initialization, so missing or vague types will break agent interaction.
Choose transport based on deployment context. Local development and CLI-based usage rely on STDIO transport, where stdout is reserved strictly for JSON-RPC messages, and all logs must go to stderr. Production deployments serving multiple users should use Streamable HTTP transport, which avoids STDIO limitations and scales more reliably. Streamable HTTP is the recommended transport for remote servers as of protocol version 2025-06-18 .
How to Build an MCP Server Step by Step Here’s a walkthrough of building an MCP server, from project setup to exposing tools and resources.
1. Set Up Your Project Structure Python (recommended approach using uv):
Alternatively, install with pip:
TypeScript:
Create a tsconfig.json file:
Update package.json to add the module type and build script:
2. Create the Server Instance Python with FastMCP (recommended):
FastMCP is included in the official MCP SDK and provides the simplest path to a working server. Decorators handle schema generation, parameter validation, and protocol compliance.
TypeScript with the low-level SDK:
3. Define Your Tools Tools let agents execute actions. Each tool requires a name, description, and input schema. The SDK validates inputs against JSON Schema Draft 2020-12 .
Python example with error handling:
TypeScript example with error handling:
Return errors as tool results, not protocol errors. The agent needs to understand what went wrong and potentially retry with different parameters.
4. Add Resources for Context Resources provide read-only data access. They use URIs to identify different data sources and return content in formats agents can understand.
Python:
TypeScript:
5. Create Prompts for Common Workflows Prompts are reusable, parameterized instruction templates that servers expose to standardize how AI agents interact with them for recurring tasks.
Python:
TypeScript:
6. Configure Transport and Run Choose stdio for local development or Streamable HTTP for remote deployments. Streamable HTTP is the recommended transport for production as of protocol version 2025-06-18 .
Python with stdio (local development):
Python with Streamable HTTP (production):
TypeScript with stdio:
Run your server:
How to Test and Debug MCP Servers Use MCP Inspector The MCP Inspector provides a browser-based testing environment with no installation required. It runs directly through npx.
For Node.js servers:
For Python servers:
For PyPI-packaged Python servers:
For npm-packaged servers:
The Inspector UI opens athttp://localhost:6274 in your browser. It provides debugging capabilities including resource inspection, prompt testing, tool execution, and real-time notification monitoring.
Test resources, prompts, and tool invocations directly through the Inspector UI before connecting to Claude Desktop. Verify that error responses include actionable guidance for agents and that resources display correct MIME types.
Connect to Claude Desktop Configure Claude Desktop to test your server with a real AI client. Edit the configuration file located at:
macOS : ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows : %APPDATA%\Claude\claude_desktop_config.json
Use this JSON structure to add your server:
This configuration follows the format specified in the MCP documentation for Claude Desktop configuration files. The three required components are:
command : The executable to run (e.g., "node", "npx", "python")args : Array of command-line arguments, with file paths specified as absolute pathsenv (optional): Environment variables to pass to the server processRestart Claude Desktop completely after saving the configuration. Use the MCP Inspector tool (npx @modelcontextprotocol/inspector) to verify your server's tools appear correctly and respond to requests. In Claude Desktop, you can test the connection by interacting with your MCP server's exposed tools in conversations.
Handle Errors Properly Return errors as tool results, not protocol exceptions. The agent needs to understand what went wrong and, if necessary, retry with different parameters. Log every request with unique identifiers for debugging.
This pattern provides several benefits:
Request IDs let you trace issues through logs Distinguishing client errors (invalid input) from server errors (internal failures) helps with debugging Returning human-readable error messages allows agents to understand what went wrong and adjust their approach. For TypeScript servers, follow the same pattern:
Note that TypeScript servers using STDIO transport must log to stderr (using console.error), not stdout. The STDIO transport reserves stdout exclusively for JSON-RPC messages.
How to Deploy an MCP Server to Production? Once your MCP server runs locally, the next step is to deploy it in a way that’s reliable, secure, and easy to operate. Here’s how to do it:
Local Deployment via STDIO STDIO transport works well for single-user, local deployments such as desktop integrations. The client launches your server as a child process and communicates through stdin/stdout. This offers the lowest latency compared to network-based transports and requires the simplest configuration.
Package your server as an npm package or Python module that users install locally. They configure their MCP client to launch your executable with appropriate environment variables.
Remote Deployment via Streamable HTTP Production deployments serving multiple clients need HTTP transport. Streamable HTTP is the recommended approach for remote deployments as of protocol version 2025-06-26. It provides better performance than the legacy SSE approach and simplifies infrastructure by using a single /mcp endpoint for all communication.
For stateless deployments that scale horizontally:
Deploy your server behind a reverse proxy (nginx, Cloudflare, AWS ALB) with TLS termination. Handle encryption at the infrastructure layer rather than in the application code. This approach simplifies certificate management and follows standard production practices.
Security Considerations Authentication : Use OAuth 2.1 with PKCE for production authentication. The MCP specification defines servers as OAuth Resource Servers that validate tokens issued by separate Authorization Servers. For simpler setups, API keys stored in environment variables or secrets managers provide basic protection.
Input validation : Validate all inputs to prevent injection attacks. Sanitize strings, check numeric ranges, and verify enum values match expected options.
Least privilege file access : Restrict file system access to specific directories. Normalize paths to prevent traversal attacks.
Environment variable management : Never include credentials in code or configuration files committed to version control.
For comprehensive security guidance, refer to the MCP security documentation and the authorization specification .
What Are Common Mistakes When Building MCP Servers? The table below shows the most common mistakes teams make when building MCP servers and how to avoid them.
Common Mistake
Why It Causes Problems
How to Avoid It
Returning raw structured data instead of readable text AI agents struggle to reason over raw objects or arrays without context, leading to misinterpretation or failed tool calls.
Serialize structured outputs into clear text with enough context for the agent to understand what the data represents.
Using vague or generic error messages Agents cannot recover from failures if they don’t understand why a tool failed or what alternatives exist.
Return agent-friendly errors that explain the reason, provide actionable guidance, and list valid retry options.
Skipping input validation Invalid or malformed inputs cause unpredictable behavior, crashes, or silent failures.
Validate inputs at both schema and runtime levels. Enforce ranges, enums, length limits, and sanitization.
Weak file path handling Poor validation enables directory traversal and unauthorized file access.
Normalize and validate paths, enforce directory allowlists, and reject all paths outside approved boundaries.
Inconsistent naming conventions Inconsistent tool and parameter names confuse agents and increase reasoning errors.
Choose one convention (e.g., snake_case or camelCase) and apply it consistently with clear prefixes.
Poor lifecycle management Leaked or improperly closed resources fail under load and break retries.
Initialize shared resources on startup, clean them up on shutdown, and keep tools stateless and idempotent.
Unbounded resource usage Unlimited concurrency exhausts memory or connections and can take services offline.
Use connection pools, concurrency limits, and defensive defaults to cap resource usage.
Inadequate logging Without structured logs, failures are hard to debug or audit in production.
Add structured logging with request IDs, execution context, and clear log levels from day one.
Granting excessive permissions Over-permissive tools increase blast radius and security risk.
Apply least-privilege by default. Restrict filesystem and system access and block writes to sensitive locations.
When Should You Use Pre-Built Infrastructure Instead? Build a custom MCP server only when you need to expose proprietary systems with no existing alternative. Internal data warehouses, company-specific business logic, and strict compliance requirements can justify custom development.
For most other cases, pre-built infrastructure is the better choice. Teams lose weeks maintaining brittle scripts that connect agents to tools like Notion, Slack, and Google Drive. APIs change, tokens expire, and integrations break, pulling engineers away from building agent behavior.
Airbyte Agents addresses this directly. The PyAirbyte MCP Server lets teams manage data connectors through AI assistants like Claude Desktop, Cursor, and Cline, without writing custom integration code. Authentication, token refresh, and API changes are handled automatically across hundreds of connectors.
For customer-facing use cases, Airbyte’s embeddable widget allows end users to connect their own data through a white-label UI. Enterprise teams also get deployment flexibility, including on-prem and hybrid options, with built-in access controls and compliance support.
Frequently Asked Questions Do I need to know MCP specification details to build a server? Use the official SDKs or FastMCP to handle protocol implementation. The SDKs manage JSON-RPC messaging, capability negotiation, and transport layers while you define tools, resources, and prompts through simple APIs.
Can one MCP server expose tools and resources together? Yes, a single server can expose any combination of tools, resources, and prompts. During initialization with the MCP protocol, servers may advertise supported capabilities, but there is no formal three-step handshake and clients only implement request handlers for the capabilities they wish to use.
Which MCP clients work with custom servers? Most clients implementing the MCP protocol, such as Cursor and Cline, can connect to custom servers through standard configuration, provided the server adheres to the protocol. However, Claude Desktop does not currently support connecting to remote MCP servers.
How do I update my server without breaking existing clients? MCP uses date-based protocol versions with explicit negotiation during initialization. Clients send their supported version in the initialize request, and servers respond with a compatible version. The protocol maintains backward compatibility within versions.
What's the difference between FastMCP and the official MCP SDK? FastMCP provides a higher-level abstraction layer built on the official Python SDK, reducing boilerplate through decorator patterns. The official SDK gives you maximum control over protocol implementation.
