Sample MCP Server

This is a complete, minimal Model Context Protocol (MCP) server written in TypeScript. It runs locally, uses the official MCP TypeScript SDK, and exposes exactly three tools:

• sayHello
• addNumbers
• getCurrentTime

The goal is learning. The code is intentionally small, commented, and direct.

What MCP Is

Model Context Protocol is a standard way for AI applications to connect to external tools and context.

Without MCP, every app invents its own custom way to call tools. With MCP, a host such as ChatGPT can talk to an MCP server using a shared protocol.

An MCP server can expose:

• Tools: actions the model can call
• Resources: data the model can read
• Prompts: reusable prompt templates

This project exposes only tools.

How This Project Works

This server uses the local stdio transport.

That means ChatGPT starts the server as a child process and communicates with it through standard input and standard output:

• ChatGPT writes JSON-RPC messages to the server's stdin.
• The server reads those messages with the MCP SDK.
• The SDK routes tool calls to our TypeScript functions.
• The server writes JSON-RPC responses back to stdout.

There is no HTTP server, no Express app, no database, no authentication, and no cloud service.

How ChatGPT Discovers Tools

When ChatGPT connects to an MCP server, it performs an initialization handshake. After that, it asks the server which tools are available.

The MCP SDK answers with each tool's:

• Name
• Description
• Input schema

For example, addNumbers tells ChatGPT that it needs two numeric inputs named a and b.

How Tool Execution Works

When ChatGPT decides to call a tool, it sends a JSON-RPC request containing:

• The tool name
• The tool arguments
• A request id so the response can be matched

The MCP SDK receives the request, validates the shape using the tool schema, and calls the matching TypeScript function.

The function returns an MCP tool result. In this project, results are text content blocks. addNumbers returns JSON as formatted text so it is easy to read.

JSON-RPC Message Flow

The message flow looks like this:

ChatGPT starts: node build/index.js
ChatGPT -> server: initialize
server -> ChatGPT: server name, version, capabilities
ChatGPT -> server: list tools
server -> ChatGPT: sayHello, addNumbers, getCurrentTime
ChatGPT -> server: call addNumbers with { "a": 2, "b": 3 }
server -> ChatGPT: { "result": 5 }

You usually do not write JSON-RPC code by hand. The SDK handles it.

Folder Structure

sample-mcp/
├── package.json
├── tsconfig.json
├── README.md
└── src/
    ├── index.ts
    ├── server.ts
    ├── tools/
    │   ├── hello.ts
    │   ├── math.ts
    │   └── time.ts
    └── types.ts

File Guide

package.json

Defines the project name, dependencies, and scripts.

Important scripts:

• npm run build compiles TypeScript into build/.
• npm start runs the compiled MCP server.

tsconfig.json

Configures TypeScript.

This project uses NodeNext module settings because the MCP SDK is designed for modern ES modules.

src/index.ts

The entry point.

It creates the server, creates the stdio transport, and connects them.

This file also catches startup errors and writes them to stderr. For stdio MCP servers, stdout must be reserved for JSON-RPC messages.

src/server.ts

Creates the McpServer instance and registers all tools.

Keeping this separate from index.ts makes the transport setup easy to understand.

src/tools/hello.ts

Registers the sayHello tool.

Input:

{
  "name": "Ada"
}

Output:

Hello Ada!

src/tools/math.ts

Registers the addNumbers tool.

Input:

{
  "a": 2,
  "b": 3
}

Output:

{
  "result": 5
}

src/tools/time.ts

Registers the getCurrentTime tool.

It accepts no input and returns the local date and time from your computer.

src/types.ts

Contains tiny helper functions for returning MCP tool results and formatting validation errors.

This keeps the tool files readable without adding a large abstraction layer.

Install Dependencies

From the project folder:

cd sample-mcp
npm install

Node.js 18 or newer is required.

Build the Server

npm run build

This compiles TypeScript from src/ into JavaScript in build/.

Run the Server

npm start

The server will appear to wait silently. That is normal.

An MCP stdio server does not print normal logs to stdout because stdout is reserved for JSON-RPC messages.

Connect It To ChatGPT

Use ChatGPT's MCP connector settings and add a local stdio server.

Use a command like this:

node D:\github\mcp\sample-mcp\build\index.js

If your path contains spaces, wrap it in quotes.

ChatGPT will start the command, initialize the MCP connection, discover the three tools, and call them when useful.

How To Add A New Tool

1. Create a new file in src/tools/.
2. Define a Zod input schema.
3. Export a function that receives server: McpServer.
4. Call server.registerTool(...).
5. Import and call your registration function in src/server.ts.

Example shape:

export function registerExampleTool(server: McpServer): void {
  server.registerTool(
    "exampleTool",
    {
      title: "Example Tool",
      description: "Explain what this tool does.",
      inputSchema: {
        value: z.string(),
      },
    },
    async (input) => {
      const parsed = schema.parse(input);
      return textResult(parsed.value);
    },
  );
}

Common Errors And Fixes

node is not recognized

Install Node.js 18 or newer, then reopen your terminal.

Check your version:

node --version

Cannot find module

Dependencies are missing.

Run:

npm install

TypeScript build fails

Run the build from inside the project folder:

cd sample-mcp
npm run build

ChatGPT does not show the tools

Make sure you built the project first:

npm run build

Then make sure ChatGPT points to the compiled file:

node D:\github\mcp\sample-mcp\build\index.js

The server prints nothing

That is expected for stdio MCP servers.

Normal text on stdout would break JSON-RPC communication, so this server only writes startup errors to stderr.

Invalid input

The tools use Zod validation. If a value has the wrong type, the tool returns a meaningful error result instead of crashing the server.

Tools Included

sayHello

Input:

{
  "name": "Grace"
}

Output:

Hello Grace!

addNumbers

Input:

{
  "a": 10,
  "b": 5
}

Output:

{
  "result": 15
}

getCurrentTime

Input:

{}

Output:

7/21/2026, 10:30:00 PM

The exact format depends on your operating system locale.