Agentic Data Engineering Resources

Resource

How to Build an MCP Server: Step-by-Step Guide

Build production-ready MCP servers with proper resource definitions, error handling, and security patterns—includes code examples and deployment tips.

Pedro Lopez

December 19, 2025

Summarize with AI:

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.

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):

<pre><code>mkdir my-mcp-server
cd my-mcp-server
uv init
uv add &quot;mcp[cli]&quot;</code></pre>

Alternatively, install with pip:

<pre><code>pip install &quot;mcp[cli]&quot;</code></pre>

TypeScript:

<pre><code>mkdir my-mcp-server
cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript</code></pre>

Create a tsconfig.json file:

<pre><code>{
  &quot;compilerOptions&quot;: {
    &quot;target&quot;: &quot;ES2022&quot;,
    &quot;module&quot;: &quot;Node16&quot;,
    &quot;moduleResolution&quot;: &quot;Node16&quot;,
    &quot;outDir&quot;: &quot;./build&quot;,
    &quot;rootDir&quot;: &quot;./src&quot;,
    &quot;strict&quot;: true,
    &quot;esModuleInterop&quot;: true,
    &quot;skipLibCheck&quot;: true,
    &quot;forceConsistentCasingInFileNames&quot;: true
  },
  &quot;include&quot;: [&quot;src/**/*&quot;],
  &quot;exclude&quot;: [&quot;node_modules&quot;]
}</code></pre>

Update package.json to add the module type and build script:

<pre><code>{
  &quot;type&quot;: &quot;module&quot;,
  &quot;scripts&quot;: {
    &quot;build&quot;: &quot;tsc &amp;&amp; chmod 755 build/index.js&quot;
  }
}</code></pre>

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.

<pre><code>import json
from mcp.server.fastmcp import FastMCP

mcp = FastMCP(&quot;my-mcp-server&quot;)

# Placeholder - replace with your actual database logic
def execute_query(query: str) -&gt; list:
    return [{&quot;id&quot;: 1, &quot;result&quot;: &quot;sample data&quot;}]

# Placeholder - replace with your actual file reading logic
def read_file(path: str) -&gt; str:
    return f&quot;Contents of {path}&quot;

@mcp.tool()
def query_database(query: str) -&gt; str:
    &quot;&quot;&quot;Execute SQL queries against the database.&quot;&quot;&quot;
    results = execute_query(query)
    return json.dumps(results, indent=2)

@mcp.resource(&quot;file:///logs/app.log&quot;)
def get_logs() -&gt; str:
    &quot;&quot;&quot;Application logs.&quot;&quot;&quot;
    return read_file(&quot;/var/logs/app.log&quot;)</code></pre>

TypeScript with the low-level SDK:

<pre><code>import { McpServer } from &quot;@modelcontextprotocol/sdk/server/mcp.js&quot;;
import { StdioServerTransport } from &quot;@modelcontextprotocol/sdk/server/stdio.js&quot;;
import { z } from &quot;zod&quot;;

const server = new McpServer({
  name: &quot;my-mcp-server&quot;,
  version: &quot;1.0.0&quot;,
});

// Placeholder - replace with your actual database logic
async function executeQuery(query: string): Promise&lt;object[]&gt; {
  return [{ id: 1, result: &quot;sample data&quot; }];
}

// Define and register a tool
server.tool(
  &quot;query_database&quot;,
  { query: z.string().describe(&quot;SQL query to execute&quot;) },
  async ({ query }) =&gt; {
    const results = await executeQuery(query);
    return {
      content: [{ type: &quot;text&quot;, text: JSON.stringify(results, null, 2) }],
    };
  }
);</code></pre>

<pre><code>// Connect via stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);
console.error(&quot;MCP Server running on stdio&quot;);</code></pre>

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:

<pre><code>import json
from mcp.server.fastmcp import FastMCP

mcp = FastMCP(&quot;database-server&quot;)

# Placeholder - replace with your actual database logic
def execute_query(query: str) -&gt; list:
    return [{&quot;id&quot;: 1, &quot;result&quot;: &quot;sample data&quot;}]

@mcp.tool()
def query_database(query: str) -&gt; str:
    ...
    &quot;&quot;&quot;Execute SQL queries against the database.

    Args:
        query: SQL query to execute
    &quot;&quot;&quot;
    if not query or not query.strip():
        return &quot;Error: 'query' parameter is required. Please provide a valid SQL query.&quot;

    try:
        results = execute_query(query)
        return f&quot;Query executed successfully. Results:\n{json.dumps(results, indent=2)}&quot;
    except Exception as e:
        return f&quot;Query execution failed: {str(e)}&quot;</code></pre>

TypeScript example with error handling:

<pre><code>// Placeholder - replace with your actual database logic
async function executeQuery(query: string): Promise&lt;object[]&gt; {
  return [{ id: 1, result: &quot;sample data&quot; }];
}

server.tool(
  &quot;query_database&quot;,
  {
    query: z.string().min(1).describe(&quot;SQL query to execute&quot;)
  },
  async ({ query }) =&gt; {
    try {
      const results = await executeQuery(query);
      return {
        content: [{
          type: &quot;text&quot;,
          text: `Query executed successfully. Results:\n${JSON.stringify(results, null, 2)}`
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: &quot;text&quot;,
          text: `Query failed: ${error instanceof Error ? error.message : String(error)}. Check your SQL syntax and try again.`
        }],
        isError: true
      };
    }
  }
);</code></pre>

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:

<pre><code># Placeholder - replace with your actual file reading logic
def read_file(path: str) -&gt; str:
    return f&quot;Contents of {path}&quot;

@mcp.resource(&quot;config://settings&quot;)
def get_settings() -&gt; str:
    &quot;&quot;&quot;Application configuration settings.&quot;&quot;&quot;
    return json.dumps({
        &quot;theme&quot;: &quot;dark&quot;,
        &quot;language&quot;: &quot;en&quot;,
        &quot;debug&quot;: False
    })

@mcp.resource(&quot;file://documents/{name}&quot;)
def read_document(name: str) -&gt; str:
    &quot;&quot;&quot;Read a document by name.&quot;&quot;&quot;
    return read_file(f&quot;/documents/{name}&quot;)</code></pre>

TypeScript:

<pre><code>server.resource(
  &quot;config://settings&quot;,
  &quot;Application Settings&quot;,
  async () =&gt; ({
    contents: [{
      uri: &quot;config://settings&quot;,
      mimeType: &quot;application/json&quot;,
      text: JSON.stringify({
        theme: &quot;dark&quot;,
        language: &quot;en&quot;,
        debug: false
      })
    }]
  })
);</code></pre>

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:

<pre><code>@mcp.prompt()
def code_review(code: str, language: str = &quot;python&quot;) -&gt; str:
    &quot;&quot;&quot;Generate a code review prompt.&quot;&quot;&quot;
    return f&quot;Please review this {language} code:\n\n{code}&quot;</code></pre>

TypeScript:

<pre><code>server.prompt(
  &quot;code_review&quot;,
  {
    code: z.string().describe(&quot;Code to review&quot;),
    language: z.string().optional().describe(&quot;Programming language&quot;)
  },
  async ({ code, language = &quot;python&quot; }) =&gt; ({
    messages: [{
      role: &quot;user&quot;,
      content: {
        type: &quot;text&quot;,
        text: `Please review this ${language} code:\n\n${code}`
      }
    }]
  })
);</code></pre>

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):

<pre><code>from mcp.server.fastmcp import FastMCP

mcp = FastMCP(&quot;my-server&quot;)

@mcp.tool()
def hello(name: str = &quot;World&quot;) -&gt; str:
    &quot;&quot;&quot;Say hello to someone.&quot;&quot;&quot;
    return f&quot;Hello, {name}!&quot;

if __name__ == &quot;__main__&quot;:
    mcp.run(transport=&quot;stdio&quot;)</code></pre>

Python with Streamable HTTP (production):

<pre><code>if __name__ == &quot;__main__&quot;:
    mcp.run(transport=&quot;streamable-http&quot;)</code></pre>

TypeScript with stdio:

<pre><code>import { StdioServerTransport } from &quot;@modelcontextprotocol/sdk/server/stdio.js&quot;;

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error(&quot;MCP Server running on stdio&quot;);
}

main().catch((error) =&gt; {
  console.error(&quot;Fatal error:&quot;, error);
  process.exit(1);
});</code></pre>

Run your server:

<pre><code># Python
uv run server.py

# or
python server.py

# TypeScript
npm run build
node build/index.js</code></pre>

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:

<pre><code>npx @modelcontextprotocol/inspector node path/to/server/index.js</code></pre>

For Python servers:

<pre><code>npx @modelcontextprotocol/inspector python path/to/server.py</code></pre>

For PyPI-packaged Python servers:

<pre><code>npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code</code></pre>

For npm-packaged servers:

<pre><code>npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop</code></pre>

The Inspector UI opens at http://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.json Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Use this JSON structure to add your server:

<pre><code>{
  &quot;mcpServers&quot;: {
    &quot;my-server&quot;: {
      &quot;command&quot;: &quot;node&quot;,
      &quot;args&quot;: [&quot;/absolute/path/to/dist/index.js&quot;],
      &quot;env&quot;: {
        &quot;API_KEY&quot;: &quot;your-api-key&quot;
      }
    }
  }
}</code></pre>

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 paths
env (optional): Environment variables to pass to the server process

Restart 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.

<pre><code>import logging
import uuid
import asyncio
from mcp.server.fastmcp import FastMCP

logger = logging.getLogger(__name__)

mcp = FastMCP(&quot;my-server&quot;)

async def fetch_api(location: str) -&gt; dict:
    &quot;&quot;&quot;Example async API call.&quot;&quot;&quot;
    await asyncio.sleep(0.1)
    return {&quot;location&quot;: location, &quot;status&quot;: &quot;ok&quot;}

@mcp.tool()
async def fetch_data(location: str) -&gt; str:
    &quot;&quot;&quot;Fetch data for a given location.&quot;&quot;&quot;
    request_id = str(uuid.uuid4())
    logger.info(f&quot;[{request_id}] Fetching data for: {location}&quot;)
    if not location:
        logger.warning(f&quot;[{request_id}] Missing location parameter&quot;)
        return &quot;Error: Location parameter is required&quot;
    try:
        result = await fetch_api(location)
        logger.info(f&quot;[{request_id}] Successfully fetched data for {location}&quot;)
        return str(result)
    except ValueError as e:
        logger.warning(f&quot;[{request_id}] Invalid input: {e}&quot;)
        return f&quot;Invalid input: {e}&quot;
    except Exception:
        logger.exception(f&quot;[{request_id}] Server error in fetch_data&quot;)
        return &quot;Internal server error occurred&quot;</code></pre>

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:

<pre><code>import { McpServer } from &quot;@modelcontextprotocol/sdk/server/mcp.js&quot;;
import { z } from &quot;zod&quot;;
import { v4 as uuidv4 } from &quot;uuid&quot;;

const server = new McpServer({
  name: &quot;my-server&quot;,
  version: &quot;1.0.0&quot;,
});

server.tool(
  &quot;fetch_data&quot;,
  { location: z.string().describe(&quot;The location to fetch data for&quot;) },
  async ({ location }) =&gt; {
    const requestId = uuidv4();
    console.error(`[${requestId}] Fetching data for: ${location}`);

    try {
      if (!location) {
        console.error(`[${requestId}] Client error: Missing location parameter`);
        return {
          isError: true,
          content: [{ type: &quot;text&quot;, text: &quot;Error: Location parameter is required&quot; }]
        };
      }
      const result = await fetchApi(location);
      console.error(`[${requestId}] Successfully fetched data for ${location}`);
      return {
        content: [{ type: &quot;text&quot;, text: String(result) }]
      };
    } catch (error) {
      console.error(`[${requestId}] Server error:`, error);
      return {
        isError: true,
        content: [{ type: &quot;text&quot;, text: &quot;Internal server error occurred&quot; }]
      };
    }
  }
);</code></pre>

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.

<pre><code>from mcp.server.fastmcp import FastMCP

mcp = FastMCP(&quot;my-local-server&quot;)

@mcp.tool()
def process_data(input: str) -&gt; str:
    &quot;&quot;&quot;Process data locally.&quot;&quot;&quot;
    return f&quot;Processed: {input}&quot;

if __name__ == &quot;__main__&quot;:
    mcp.run()  # Uses STDIO transport by default</code></pre>

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.

<pre><code>from mcp.server.fastmcp import FastMCP

mcp = FastMCP(&quot;my-remote-server&quot;)

@mcp.tool()
def fetch_data(query: str) -&gt; str:
    &quot;&quot;&quot;Fetch data from the server.&quot;&quot;&quot;
    return f&quot;Results for: {query}&quot;

if __name__ == &quot;__main__&quot;:
    mcp.run(
        transport=&quot;streamable-http&quot;,
        host=&quot;0.0.0.0&quot;,
        port=8000
    )</code></pre>

For stateless deployments that scale horizontally:

<pre><code>mcp = FastMCP(&quot;my-stateless-server&quot;, stateless_http=True)

if __name__ == &quot;__main__&quot;:
    mcp.run(transport=&quot;streamable-http&quot;, host=&quot;0.0.0.0&quot;, port=8000)</code></pre>

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.

<pre><code>import os
from mcp.server.fastmcp import FastMCP

mcp = FastMCP(&quot;secure-server&quot;)

def get_api_key() -&gt; str:
    &quot;&quot;&quot;Load API key from environment.&quot;&quot;&quot;
    key = os.getenv(&quot;MCP_API_KEY&quot;)
    if not key:
        raise ValueError(&quot;MCP_API_KEY environment variable not set&quot;)
    return key

@mcp.tool()
def authenticated_action(request: str) -&gt; str:
    &quot;&quot;&quot;Perform an action that requires authentication.&quot;&quot;&quot;
    api_key = get_api_key()
    # Use api_key for downstream service calls
    return f&quot;Authenticated request processed: {request}&quot;</code></pre>

Input validation: Validate all inputs to prevent injection attacks. Sanitize strings, check numeric ranges, and verify enum values match expected options.

<pre><code>import re
from mcp.server.fastmcp import FastMCP

mcp = FastMCP(&quot;validated-server&quot;)

MAX_INPUT_LENGTH = 10000

def sanitize_string(input_str: str) -&gt; str:
    &quot;&quot;&quot;Sanitize string input.&quot;&quot;&quot;
    if len(input_str) &gt; MAX_INPUT_LENGTH:
        raise ValueError(f&quot;Input exceeds maximum length of {MAX_INPUT_LENGTH}&quot;)
    # Remove control characters
    cleaned = re.sub(r'[\x00-\x1F\x7F]', '', input_str)
    return cleaned

def validate_numeric_range(value: float, min_val: float, max_val: float) -&gt; float:
    &quot;&quot;&quot;Validate numeric value is within acceptable range.&quot;&quot;&quot;
    if not (min_val &lt;= value &lt;= max_val):
        raise ValueError(f&quot;Value {value} out of range [{min_val}, {max_val}]&quot;)
    return value

@mcp.tool()
def process_user_input(text: str, count: int) -&gt; str:
    &quot;&quot;&quot;Process user input with validation.&quot;&quot;&quot;
    clean_text = sanitize_string(text)
    valid_count = validate_numeric_range(count, 1, 1000)
    return f&quot;Processed '{clean_text}' with count {valid_count}&quot;</code></pre>

Least privilege file access: Restrict file system access to specific directories. Normalize paths to prevent traversal attacks.

<pre><code>import os
from mcp.server.fastmcp import FastMCP

mcp = FastMCP(&quot;file-server&quot;)

ALLOWED_DIRECTORIES = [&quot;/app/data&quot;, &quot;/app/config&quot;]

@mcp.tool()
def read_file(path: str) -&gt; str:
    &quot;&quot;&quot;Read file contents with path traversal protection.&quot;&quot;&quot;
    # Normalize path to prevent traversal attacks
    normalized = os.path.normpath(os.path.abspath(path))
    # Validate path is within allowed directories
    if not any(normalized.startswith(d) for d in ALLOWED_DIRECTORIES):
        return f&quot;Access denied: Path '{path}' is outside allowed directories&quot;
    try:
        with open(normalized, 'r') as f:
            return f.read()
    except FileNotFoundError:
        return f&quot;File not found: {path}&quot;
    except Exception as e:
        return f&quot;Error reading file: {str(e)}&quot;</code></pre>

Environment variable management: Never include credentials in code or configuration files committed to version control.

<pre><code>import os
from dataclasses import dataclass

@dataclass
class ServerConfig:
    &quot;&quot;&quot;Server configuration loaded from environment.&quot;&quot;&quot;
    api_key: str
    database_url: str
    debug: bool

    @classmethod
    def from_environment(cls) -&gt; &quot;ServerConfig&quot;:
        api_key = os.getenv(&quot;MCP_API_KEY&quot;)
        database_url = os.getenv(&quot;DATABASE_URL&quot;)
        if not api_key:
            raise ValueError(&quot;MCP_API_KEY environment variable required&quot;)
        if not database_url:
            raise ValueError(&quot;DATABASE_URL environment variable required&quot;)
        return cls(
            api_key=api_key,
            database_url=database_url,
            debug=os.getenv(&quot;DEBUG&quot;, &quot;false&quot;).lower() == &quot;true&quot;
        )</code></pre>

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. This leads 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 do not understand why a tool failed or what valid alternatives exist.	Return errors designed for agent consumption. Include the reason for failure, actionable guidance, and a list of valid options the agent can retry with.
Skipping input validation	Invalid or malformed inputs cause unpredictable behavior, crashes, or silent failures that are hard to debug.	Validate inputs at both the schema level and runtime level. Enforce value ranges, expected enum values, maximum lengths, and sanitized input before processing.
Weak file path handling	Poor path validation exposes servers to directory traversal and unauthorized file access.	Normalize and validate all paths. Restrict access to an explicit allowlist of directories and reject any paths outside those boundaries.
Inconsistent naming conventions	Inconsistent tool and parameter names confuse agents and increase reasoning errors across tool calls.	Choose a single convention, such as snake_case or camelCase, and apply it consistently. Use clear prefixes to group related tools.
Poor lifecycle management	Resources like database connections leak or fail under load if startup and shutdown are not handled cleanly.	Initialize shared resources during server startup and clean them up on shutdown. Keep tools stateless and idempotent to support retries.
Unbounded resource usage	Without limits, concurrent requests can exhaust connections or memory and take the server offline.	Use connection pools with configurable limits and defensive defaults to control concurrency and resource usage.
Inadequate logging	Without structured logs, production issues are difficult to trace and audit after failures occur.	Add structured logging from day one. Include request IDs, execution context, and appropriate log levels for success, warnings, and errors.
Granting excessive permissions	Over-permissive tools increase the blast radius of mistakes and create serious security risks.	Apply least-privilege access by default. Restrict filesystem and system access and never allow 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. Teams evaluating options can also review Agent SDK and For Developers resources if they want a more developer-focused path for working with agent-facing integrations. Airbyte Agents and Agent MCP let teams manage agent connectors through AI assistants like Claude Desktop and Cursor, without writing custom integration code. Authentication, token refresh, and API changes are handled automatically across hundreds of agent connectors.

If you want a simpler path to production, Context Store and managed infrastructure can reduce the amount of custom integration work your team needs to maintain. Get a demo to see how Airbyte Agents helps teams build and operate MCP servers for production AI agents, or try Airbyte Agents today.

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.

Try Airbyte Agents

Airbyte connects your agents to all of your data and assembles context before they run. Build agents that actually know your business.

Try it free Talk to sales

How to Build an MCP Server: Step-by-Step Guide

Related posts

Try Airbyte Agents