Quickstart Guide

Build and run your first MCP server in under 5 minutes with step-by-step instructions

Get Your First MCP Server Running

This guide will walk you through setting up, building, and testing your first MCP server. We’ll use the TypeScript Game of Thrones quotes server as our example, but you can follow similar steps for Python or Go.

By the end of this guide, you’ll have a working MCP server that can fetch quotes, perform calculations, and respond to prompts.

Prerequisites

Before you begin, make sure you have:

Node.js

Version 18 or higher for TypeScript examples

Python

Version 3.10 or higher for Python examples

Git

To clone the course repository

Code Editor

VS Code, Cursor, or your preferred editor

Step-by-Step Tutorial

1. Clone the Repository

   First, clone the MCP Course repository to get access to all the example code:

   git clone https://github.com/alexyslozada/mcp-course.git
   cd mcp-course
   

   The repository structure looks like this:

   mcp-course/
   ├── servers/           # MCP server implementations
   │   ├── basic/         # TypeScript: Game of Thrones quotes
   │   ├── calculator-py/ # Python: Calculator operations
   │   └── todo-ts/       # TypeScript: Todo management
   └── clients/           # MCP client implementations
       ├── basic-ts/      # TypeScript client
       └── basic-py/      # Python client
   

   Each server directory contains a complete, working example you can learn from and modify.

2. Navigate to the Server Directory

   Let’s start with the TypeScript server that includes multiple features:

   cd servers/basic
   

   Take a look at the package.json to see the dependencies:

   {
     "name": "basic",
     "version": "1.0.0",
     "type": "module",
     "dependencies": {
       "@modelcontextprotocol/sdk": "^1.7.0",
       "@types/node": "^22.13.13",
       "node-fetch": "^3.3.2",
       "typescript": "^5.8.2"
     },
     "scripts": {
       "build": "tsc",
       "start": "node dist/server.js"
     }
   }
   

   The key dependency is @modelcontextprotocol/sdk, which provides all the MCP functionality.

3. Install Dependencies

   Install the required packages:

   npm install
   

   This will install:

   • The official MCP SDK for TypeScript
   • Zod for schema validation
   • Node-fetch for API calls
   • TypeScript compiler

   Make sure you’re using Node.js 18 or higher. Check with node --version.

4. Build the Server

   Compile the TypeScript code to JavaScript:

   npm run build
   

   This creates a dist/ directory with the compiled JavaScript files. You should see output like:

   > basic@1.0.0 build
   > tsc
   

   If the build succeeds, you’re ready to run the server!

5. Understand the Server Code

   Before running the server, let’s look at what it does. Open src/server.ts:

   Tool Definition

   // Define a tool that fetches random quotes
   server.tool(
     "get_random_quotes",
     { count: z.number().optional().default(5) },
     async ({ count }) => {
       try {
         const quotes = await fetchRandomQuotes(count);
         const formattedQuotes = quotes.map(formatQuote);
         
         return {
           content: [{ 
             type: "text", 
             text: formattedQuotes.join("\n---\n") 
           }]
         };
       } catch (error) {
         return {
           content: [{ 
             type: "text", 
             text: `Error: ${error.message}` 
           }],
           isError: true
         };
       }
     }
   );
   

   // Define a resource for random quotes
   server.resource(
     "random-quotes",
     "got://quotes/random",
     async (uri) => {
       const quotes = await fetchRandomQuotes(5);
       const formattedQuotes = quotes.map(formatQuote);
       
       return {
         contents: [{
           uri: uri.href,
           text: formattedQuotes.join("\n---\n"),
           mimeType: "text/plain"
         }]
       };
     }
   );
   

   // Define a prompt for code review
   server.prompt(
     "code_review",
     { code: z.string() },
     async ({ code }) => {
       return {
         description: "Code Review",
         messages: [
           {
             role: "assistant",
             content: {
               type: "text",
               text: "You are an expert software engineer..."
             }
           },
           {
             role: "user",
             content: {
               type: "text",
               text: `Please review the following code:\n\n${code}`
             }
           }
         ]
       };
     }
   );
   

   This server exposes:

   • 2 Tools: get_random_quotes and lcm (least common multiple)
   • 2 Resources: Random quotes and person properties
   • 2 Prompts: Game of Thrones analysis and code review
6. Run the Server

   Start the MCP server:

   npm start
   

   The server is now running and waiting for connections via stdio (standard input/output).

   MCP servers typically communicate through stdio, which means they don’t print anything to the console. They’re waiting for a client to connect and send requests.

   To test the server, you’ll need to connect a client. Keep this terminal open and open a new one for the next step.

7. Connect a Client

   In a new terminal, navigate to the TypeScript client:

   cd clients/basic-ts
   npm install
   

   The client code shows how to connect to the server:

   Client Connection

   import { Client } from "@modelcontextprotocol/sdk/client/index.js";
   import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
   
   // Create a transport that connects to the server
   const transport = new StdioClientTransport({
     command: "node",
     args: ["path/to/server.js"]
   });
   
   // Create and connect the client
   const client = new Client(
     {
       name: "basic-client",
       version: "1.0.0"
     },
     {
       capabilities: {
         prompts: {},
         resources: {},
         tools: {}
       }
     }
   );
   
   await client.connect(transport);
   

   You’ll need to update the path in the client code to point to your compiled server. Change the path in src/index.ts to match your local setup.

8. Test the Server

   Run the client to test all server capabilities:

   npm start
   

   You should see output showing:

   Available Tools:

   {
     "tools": [
       {
         "name": "get_random_quotes",
         "description": "",
         "inputSchema": {
           "type": "object",
           "properties": {
             "count": {
               "type": "number",
               "default": 5
             }
           }
         }
       },
       {
         "name": "lcm",
         "description": "Calculate the least common multiple of a list of numbers",
         "inputSchema": {
           "type": "object",
           "properties": {
             "numbers": {
               "type": "array",
               "items": { "type": "number" },
               "minItems": 2
             }
           }
         }
       }
     ]
   }
   

   Tool Execution Result:

   {
     "content": [
       {
         "type": "text",
         "text": "The least common multiple is: 60"
       }
     ]
   }
   

   Resource Data:

   {
     "contents": [
       {
         "uri": "got://quotes/random",
         "mimeType": "text/plain",
         "text": "Quote: \"Winter is coming\"\nCharacter: Ned Stark\nHouse: House Stark\n---\n..."
       }
     ]
   }
   

   The client code demonstrates all MCP operations: listing capabilities, calling tools, reading resources, and getting prompts.

Try Other Examples

Now that you have the basic server running, try the other examples:

Python Calculator

cd servers/calculator-py
pip install mcp
python server.py

cd servers/todo-ts
npm install
npm run build
npm start

Python Calculator Server

The Python example uses FastMCP for a simpler API:

Python Server Example

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Calculator MCP Server")

@mcp.tool()
def calculate(a: float, b: float, operation: str) -> float:
    if operation == "add":
        return float(a + b)
    elif operation == "subtract":
        return float(a - b)
    elif operation == "multiply":
        return float(a * b)
    elif operation == "divide":
        if b == 0:
            raise ValueError("No se puede dividir por cero")
        return float(a / b)
    else:
        raise ValueError("Operación no válida")

if __name__ == "__main__":
    mcp.run(transport='stdio')

Test it with the Python client:

cd clients/basic-py
python main.py

What’s Next?

Now that you have a working MCP server, you can:

Learn the Protocol

Understand how MCP works under the hood

Build Custom Tools

Create your own tools for specific use cases

Explore Examples

Deep dive into the server implementations

Integrate with LLMs

Connect your server to Ollama or Claude

Troubleshooting

Server doesn't start

Check Node.js version: Make sure you’re using Node.js 18 or higher

node --version

Check TypeScript compilation: Look for errors in the build step

npm run build

Verify dependencies: Reinstall packages if needed

rm -rf node_modules package-lock.json
npm install

Client can't connect

Update the server path: Make sure the client points to the correct server location

In clients/basic-ts/src/index.ts, update:

const transport = new StdioClientTransport({
  command: "node",
  args: ["/absolute/path/to/servers/basic/dist/server.js"]
});

Check server is running: The server must be compiled and the path must exist

Import errors in TypeScript

Check package.json type: Make sure "type": "module" is set

Use .js extensions: Import statements need .js even for TypeScript files:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

This is required for ES modules in TypeScript.

Python import errors

Install MCP SDK: Make sure the package is installed

pip install mcp

Check Python version: Use Python 3.10 or higher

python --version

Use virtual environment: Recommended for isolation

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install mcp

Still having issues? Check the GitHub repository for the latest code and examples.