How to Set Up Your First MCP Server

How to Set Up Your First MCP Server

The Model Context Protocol (MCP) transforms standard large language model chat interfaces into capable, agentic development assistants. By connecting local applications to specialized MCP servers, your AI assistant gains the ability to read workspace files, query private databases, execute terminal diagnostics, and integrate with external APIs.

For developers new to the protocol, setting up a first server can seem daunting due to configuration paths, process lifecycles, and cross-platform operating system differences. However, the protocol architecture is fundamentally straightforward: an AI host launches an MCP server as a local child process and exchanges structured JSON-RPC 2.0 messages over standard input and output (stdio).

This tutorial guides you through installing, configuring, and testing your very first MCP server—the official Filesystem server—across Claude Desktop, Cursor, and OpenAI Codex CLI, followed by authoring a custom TypeScript server from scratch.

1. Understanding the MCP Client-Server Architecture

Before editing configuration files, it helps to understand the three primary components of the Model Context Protocol ecosystem:

1. ▸The MCP Host: The client application (such as Claude Desktop, Cursor IDE, or OpenAI Codex CLI) that runs the reasoning model and orchestrates tool execution.
2. ▸The MCP Transport: The communication bridge. For local desktop servers, communication occurs over standard input and standard output streams (stdio). For remote enterprise clusters, messages stream over Server-Sent Events (SSE) or HTTP.
3. ▸The MCP Server: A lightweight executable program that exposes structured tools, contextual resources, and prompt templates to the host.

2. Prerequisites and Environment Matrix

Ensure that your development workstation has the necessary runtime dependencies installed before proceeding:

Create a dedicated local folder to serve as your safe testing sandbox:

# macOS and Linux
mkdir -p ~/mcp-sandbox

# Windows PowerShell
New-Item -ItemType Directory -Force -Path "$HOME\mcp-sandbox"

3. Configuration Across Primary AI Hosts

Locate your host application's configuration file. Because JSON files do not tolerate syntax errors or trailing commas, format your changes carefully.

Claude Desktop Configuration

Claude Desktop stores its configuration at the following OS-specific file paths:

• ▸macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• ▸Windows: %APPDATA%\Claude\claude_desktop_config.json (resolving to C:\Users\<Username>\AppData\Roaming\Claude\claude_desktop_config.json)

Open or create claude_desktop_config.json and insert the filesystem server declaration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/mcp-sandbox"
      ]
    }
  }
}

[!IMPORTANT] On Windows, replace /Users/username/mcp-sandbox with your Windows path formatted with forward slashes (e.g. C:/Users/username/mcp-sandbox). Never use raw single backslashes in JSON configuration files, as backslashes act as escape sequences.

Cursor IDE Configuration

In Cursor, open project settings or create a .cursor/mcp.json file in your project root:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "./mcp-sandbox"
      ]
    }
  }
}

OpenAI Codex CLI Configuration

In your terminal user directory, open ~/.codex/config.toml:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/mcp-sandbox"]

4. Restarting the Host and Verifying Tool Discovery

Once you have saved your configuration file, apply the changes:

1. ▸Quit the Host Completely: In Claude Desktop, close the window, right-click the application icon in the macOS Dock or Windows System Tray, and select Quit.
2. ▸Relaunch the Application: Reopen Claude Desktop.
3. ▸Inspect the Hammer Icon: Look at the bottom-right corner of the prompt input box. You should now see a Hammer icon (🔨). Clicking or hovering over it reveals the discovered tools:
   • ▸read_file: Reads full content from a file.
   • ▸write_file: Creates or replaces file contents.
   • ▸list_directory: Lists directory contents.
   • ▸directory_tree: Recursively maps project files.
4. ▸Issue a Test Prompt: Send this verification prompt to the model:

   "List the contents of my sandbox directory and write a file named hello.txt containing 'Hello from MCP!' inside it."

The model will trigger the write_file tool call and report successful execution.

5. Building Your Own Custom "Hello World" MCP Server

To understand the internal mechanics, you can build a custom server in TypeScript using the official @modelcontextprotocol/sdk.

Step 1: Initialize Project Directory

mkdir my-first-mcp-server
cd my-first-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install typescript @types/node --save-dev
npx tsc --init

Step 2: Implement the Server (src/index.ts)

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

const server = new Server(
  { name: 'hello-world-server', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

// 1. Expose Available Tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'say_hello',
        description: 'Returns a friendly greeting with current server timestamp.',
        inputSchema: {
          type: 'object',
          properties: {
            name: { type: 'string', description: 'Name of the user to greet' }
          },
          required: ['name']
        }
      }
    ]
  };
});

// 2. Handle Tool Invocations
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'say_hello') {
    const userName = (request.params.arguments?.name as string) || 'Developer';
    const timestamp = new Date().toISOString();

    return {
      content: [
        {
          type: 'text',
          text: `Hello, ${userName}! Your MCP server is operating successfully at ${timestamp}.`
        }
      ]
    };
  }

  throw new Error(`Tool ${request.params.name} not found.`);
});

// 3. Connect via Standard Input/Output
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch((err) => {
  process.stderr.write(`Server error: ${err.message}\n`);
  process.exit(1);
});

Compile with npx tsc and register the generated dist/index.js file in your client configuration.

6. Common Errors and Production Troubleshooting

When configuring and launching your first MCP servers, keep these standard error resolutions handy:

Error: spawn npx ENOENT

• ▸Root Cause: The host application could not find the npx executable in its default system environment.
• ▸Resolution: Provide the absolute path to your binary:
  • ▸macOS / Linux: /usr/local/bin/npx or /opt/homebrew/bin/npx (check with which npx)
  • ▸Windows: C:\\Program Files\\nodejs\\npx.cmd

Error: Missing Hammer Icon (Silent Initialization Failure)

• ▸Root Cause: A syntax error in claude_desktop_config.json caused Claude to ignore the file, or the child process crashed during startup.
• ▸Resolution: Inspect the local MCP log file:
  • ▸macOS: ~/Library/Logs/Claude/mcp.log
  • ▸Windows: %APPDATA%\Claude\logs\mcp.log

Error: Terminal Hangs Awaiting Package Confirmation

• ▸Root Cause: Invoking npx without the automatic approval flag -y pauses the background process while waiting for user confirmation.
• ▸Resolution: Always ensure "-y" is the first element in your args array.

7. External Citations and Security Guardrails

As you expand your local MCP toolchain, adhere to security best practices:

• ▸Scope Directory Permissions: Never configure the filesystem server to expose your root directory (/ or C:/) or user home directory. Expose only project-specific subdirectories.
• ▸Official Standards and Repositories:
  • ▸Official Model Context Protocol Specification (opens in a new tab)
  • ▸Model Context Protocol GitHub Reference Servers (opens in a new tab)
  • ▸Official TypeScript SDK on npm (opens in a new tab)