MCP Docs

Quick Start

Get started quickly with Model Context Protocol implementation

MCP Quick Start Guide

This guide provides a practical approach to implementing Model Context Protocol in your applications, with beginner-friendly explanations and examples. Follow these steps to quickly set up and understand MCP servers and clients.

Choose Your Path

If you just want to use MCP with existing applications like Claude Desktop:

1. Install Claude Desktop

Download and install Claude Desktop for your operating system.

2. Configure MCP Servers

  1. Open Claude Desktop
  2. Click on the Claude menu and select "Settings..."
  3. Click on "Developer" in the left sidebar
  4. Click "Edit Config" to open your configuration file

3. Add a Filesystem Server

Replace the file contents with this configuration (adjust the paths for your system):

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

Remember to replace username with your actual username.

4. Restart Claude and Try It Out

After saving the configuration, restart Claude Desktop and you should see a hammer icon in the chat interface. You can now ask Claude to interact with files on your desktop or in your downloads folder!

You need to have Node.js installed for this example. If you don't have it yet, download it from nodejs.org.

Installation

First, set up a new project and install the MCP SDK:

# Create a new directory
mkdir my-mcp-project
cd my-mcp-project
 
# Initialize a new npm project
npm init -y
 
# Install the MCP SDK
npm install @modelcontextprotocol/sdk
 
# For TypeScript support
npm install typescript @types/node --save-dev
npx tsc --init

Building a Simple MCP Server

Let's create a weather server that provides weather forecasts and alerts as tools.

Create your server file

Create a file named weather-server.ts:

import { Server } from "@modelcontextprotocol/sdk/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
 
async function main() {
  // Create a new MCP server
  const server = new Server({
    name: "weather-server",
    version: "1.0.0"
  }, {
    capabilities: {
      tools: {}
    }
  });
  
  // Define available tools
  server.setRequestHandler("tools/list", async () => {
    return {
      tools: [
        {
          name: "get_forecast",
          description: "Get weather forecast for a location",
          inputSchema: {
            type: "object",
            properties: {
              location: {
                type: "string",
                description: "City name or location"
              }
            },
            required: ["location"]
          }
        },
        {
          name: "get_alerts",
          description: "Get active weather alerts for a location",
          inputSchema: {
            type: "object",
            properties: {
              location: {
                type: "string",
                description: "City name or state code"
              }
            },
            required: ["location"]
          }
        }
      ]
    };
  });
  
  // Handle tool execution
  server.setRequestHandler("tools/call", async (request) => {
    const { name, arguments: args } = request.params;
    
    if (name === "get_forecast") {
      const location = args.location;
      // In a real implementation, you would call a weather API here
      return {
        content: [
          {
            type: "text",
            text: `The forecast for ${location} is sunny with a high of 75°F.`
          }
        ]
      };
    }
    
    if (name === "get_alerts") {
      const location = args.location;
      // In a real implementation, you would call a weather API here
      return {
        content: [
          {
            type: "text",
            text: `No active weather alerts for ${location}.`
          }
        ]
      };
    }
    
    throw new Error(`Unknown tool: ${name}`);
  });
  
  // Connect the server using stdio transport
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Server started"); // Use stderr for logging
}
 
main().catch(err => console.error("Error:", err));

This is a simplified example. In a real implementation, you would connect to a weather API service to get actual forecasts and alerts.

Run your server

# Compile TypeScript to JavaScript
npx tsc weather-server.ts
 
# Run the server
node weather-server.js

The server will start and wait for client connections. Since it's using stdio transport, it won't display any output until a client connects.

Test with Claude Desktop

The easiest way to test your server is to connect it to Claude Desktop:

  1. Open your Claude Desktop configuration file
  2. Add your weather server configuration:
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/full/path/to/your/weather-server.js"]
    }
  }
}

Or for Python:

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/full/path/to/your/weather_server.py"]
    }
  }
}
  1. Restart Claude Desktop
  2. Ask weather-related questions like "What's the weather forecast for New York?" and Claude will use your weather server.

Test with MCP Inspector

Alternatively, you can use the MCP Inspector tool to test your server:

# Install and run MCP Inspector
npx -y @modelcontextprotocol/inspector node weather-server.js

Or for Python:

npx -y @modelcontextprotocol/inspector python weather_server.py

The MCP Inspector will open in your browser and allow you to interact with your server, test tools, and view logs.

Building an MCP Client

Now let's create a simple client that connects to your weather server:

Create a file named weather-client.ts:

import { spawn } from "child_process";
import { ClientSession } from "@modelcontextprotocol/sdk/client";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio";
 
async function main() {
  // Start the weather server process
  const serverProcess = spawn("node", ["weather-server.js"]);
  
  // Create stdio transport
  const { input, output } = new StdioClientTransport({
    input: serverProcess.stdout,
    output: serverProcess.stdin
  });
  
  // Create and initialize a client session
  const session = new ClientSession(input, output);
  await session.initialize();
  
  // List available tools
  const toolsResponse = await session.listTools();
  console.log("Available tools:");
  toolsResponse.tools.forEach(tool => {
    console.log(`- ${tool.name}: ${tool.description}`);
  });
  
  // Call a tool
  console.log("\nGetting forecast for San Francisco...");
  const forecastResult = await session.callTool("get_forecast", { location: "San Francisco" });
  console.log("Result:", forecastResult.content[0].text);
  
  // Call another tool
  console.log("\nChecking weather alerts for California...");
  const alertsResult = await session.callTool("get_alerts", { location: "California" });
  console.log("Result:", alertsResult.content[0].text);
  
  // Clean up
  await session.shutdown();
  serverProcess.kill();
}
 
main().catch(err => console.error("Error:", err));

Run your client to test the connection to the server:

# Compile and run the client
npx tsc weather-client.ts
node weather-client.js

Next Steps

Congratulations! You've created your first MCP server and client. Here are some ways to expand on this foundation:

Add Resources

Enhance your server to provide data resources in addition to tools. Learn how to expose and manage resources.

Add Prompts

Create reusable prompt templates for common interactions to standardize AI workflows.

Connect to Real APIs

Replace the hardcoded responses with real API calls to external services or databases.

Deploy with SSE

Deploy your server with Server-Sent Events for remote access across the network.

Check out the Example Servers for more complete implementations and inspiration.

Debugging Tips

If you encounter issues with your MCP server or client:

  1. Use MCP Inspector: The best tool for testing and debugging servers
  2. Check Logs: MCP servers should log to stderr, not stdout
  3. Verify JSON Schema: Make sure your tool schemas are valid
  4. Test Tool Execution: Try calling your tools directly through the Inspector
  5. Check Claude Desktop Logs: If using Claude Desktop, check its log files for errors

For more comprehensive debugging strategies, see our Debugging Guide.

How is this guide?

Protocol Details

Understanding how MCP components communicate with each other

Resources

Learn how MCP provides AI models with access to data through resources

On this page