Building Your First MCP Server: A Step-by-Step Developer Guide (2026)

The Model Context Protocol (MCP) has fundamentally changed how AI agents interact with the outside world. By providing a universal, standardized interface for tools, prompts, and resources, MCP eliminates the need to write custom integration code for every new LLM or agent framework.

If you are an API developer or platform engineer, exposing your services via an MCP server is the fastest way to make your data accessible to AI systems like Claude, Cursor, and custom enterprise agents.

This technical guide provides a step-by-step walkthrough for building, securing, and deploying a robust MCP server using Node.js and TypeScript.

1. Executive Summary

• The Problem: Integrating APIs with multiple AI agents requires maintaining fragile, bespoke integration layers for each agent framework.
• The Solution: Building an MCP Server standardizes your API’s capabilities into Tools and Resources that any compliant AI agent can automatically discover and use.
• The Output: A production-ready TypeScript MCP server that exposes local file system operations or external API data securely.

2. Core Concepts: What Makes an MCP Server?

An MCP server communicates via JSON-RPC. It typically provides three core primitives:

1. Tools: Executable functions that cause side effects or perform complex calculations (e.g., execute_query, send_message).
2. Resources: Read-only data that provides context to the LLM (e.g., log files, API schemas).
3. Prompts: Pre-defined instruction templates the server provides to the client to ensure consistent formatting.

3. Step-by-Step Implementation Guide

We will build a simple MCP server that allows an AI agent to fetch real-time weather data and manage a local to-do list.

Step 1: Project Setup

Initialize a new TypeScript project and install the official MCP SDK.

mkdir mcp-weather-server
cd mcp-weather-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node ts-node
npx tsc --init

Step 2: Initialize the MCP Server

Create src/index.ts. We will set up the server using the stdio transport, which is ideal for local agent environments like Cursor or Claude Code.

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";

const server = new Server(
  {
    name: "weather-todo-mcp",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

Step 3: Registering Tools

Next, we define the tools our server provides. The AI agent will request the ListToolsRequestSchema to discover these capabilities.

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "get_weather",
        description: "Fetch the current weather for a specific city.",
        inputSchema: {
          type: "object",
          properties: {
            city: {
              type: "string",
              description: "The name of the city (e.g., 'San Francisco')",
            },
          },
          required: ["city"],
        },
      },
    ],
  };
});

Step 4: Executing Tool Calls

When the AI decides to use a tool, it sends a CallToolRequestSchema. We must handle the execution and return a structured response.

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "get_weather") {
    const city = request.params.arguments?.city as string;
    
    // In production, call a real weather API here
    const mockWeather = `The weather in ${city} is currently 72°F and sunny.`;
    
    return {
      content: [
        {
          type: "text",
          text: mockWeather,
        },
      ],
    };
  }

  throw new Error("Tool not found");
});

Step 5: Starting the Transport

Finally, connect the server to the standard input/output streams.

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

main().catch(console.error);

4. Architecture and Deployment Options

How you deploy your MCP server dictates how agents interact with it.

graph TD
    Client["AI Agent (Cursor/Claude)"]
    
    subgraph Deployment Methods
        Client -- "Stdio (Local)" --> LocalNode["Local Node.js Process"]
        Client -- "SSE (Remote)" --> CloudRun["CloudRun / ECS Service"]
    end
    
    LocalNode --> DB1["Local Files/DB"]
    CloudRun --> DB2["Production DB"]
    
    style Deployment Methods fill:#09090b,stroke:#e5e7eb,stroke-width:1px,color:#fff

Local Execution (stdio)

Best for developer tools, IDE integrations, and personal assistants. The agent spawns the server as a child process.

Remote Execution (SSE)

Best for enterprise data, SaaS integrations, and shared services. The server is hosted on a cloud provider, and agents connect via HTTP Server-Sent Events.

5. Best Practices & Security

1. Always Validate Input: Never trust arguments passed by the LLM. Use libraries like zod to strictly validate all incoming parameters before execution.
2. Fail Gracefully: Return clear error messages in the tool response (not as a system crash) so the LLM knows why the tool failed and can attempt to correct its parameters.
3. Authentication: For SSE deployments, secure your endpoints using standard Bearer tokens or API keys. The MCP protocol supports sending custom headers during initialization.

6. Key Takeaways

1. Standardization: MCP servers turn proprietary APIs into universal capabilities that any compliant AI agent can instantly understand and use.
2. Schema is King: The quality of your inputSchema directly dictates how reliably the LLM can call your tool. Provide detailed descriptions for every parameter.
3. Transport Flexibility: Start with stdio for local testing, then easily transition to SSE for production deployments without changing your core logic.