Minimal MCP Demo

This is a very small Model Context Protocol (MCP) example.

The goal is to show the basic architecture in the simplest possible way:

• a server exposes tools

• a client calls those tools

• both communicate over stdio

Architecture

1. Server

The server is the part that knows how to do work.

In this project, the server:

• creates an MCP server instance

• registers a tool named get_weather

• waits for incoming requests

The server code is in:

• src/server.ts

• src/index.ts

2. Tool

A tool is a function the server exposes to the client.

Here, the tool is called get_weather.

When the client calls it, the server:

• reads the input (city, optional country)

• creates a fake weather response

• returns the result as structured data and text

3. Client

The client is the part that asks the server to do something.

It:

• starts the server as a child process

• sends a tools/call request

• prints the result

The client code is in:

• src/client.ts

4. Stdio transport

stdio means standard input/output.

This is the communication channel used by the MCP server and client.

In simple terms:

• the client writes a request to the server's stdin

• the server reads it

• the server writes the response to stdout

• the client reads the response

This is why the server uses:

const transport = new StdioServerTransport();
await server.connect(transport);

and the client uses:

const transport = new StdioClientTransport({
  command: "node",
  args: ["build/index.js"],
});

Related MCP server: MCP Server Demo

Request flow

Here is the full flow in one simple sequence:

1. Client launches the server

2. Client sends tools/call for get_weather

3. Server receives the request

4. Server runs the tool function

5. Server returns text + JSON data

6. Client prints the response

Sequence diagram

sequenceDiagram
    participant Client
    participant Server
    participant Tool

    Client->>Server: Launch process over stdio
    Client->>Server: tools/call { name: "get_weather", arguments: { city, country } }
    Server->>Tool: Execute get_weather
    Tool-->>Server: Return weather result
    Server-->>Client: JSON response with content + structuredContent
    Client->>Client: Print result

Files in this project

• src/server.ts - server implementation

• src/index.ts - server entry point

• src/client.ts - client implementation

• package.json - scripts to build and run

Run the demo

Install dependencies:

npm install

Build the project:

npm run build

Run the server:

npm start

Then, in another terminal, run the client:

npm run client

You should see a successful get_weather response.

Normal client-server vs MCP

A normal client-server app usually looks like this:

• client sends an HTTP request to a server

• server is already running on a port like 3000

• server responds with JSON

• both sides communicate over the network

An MCP server is different:

• the server is usually a local process

• the client launches it and communicates over stdio

• the server exposes tools, not general web endpoints

• the client sends MCP protocol messages like tools/call

Simple comparison

In one sentence

A normal client-server app is built for app-to-app communication, while an MCP server is built for AI/host-to-tool communication.

Mental model

Think of it like this:

• Server = worker

• Tool = job the worker can do

• Client = person asking the worker to do the job

• Stdio = the communication pipe between them

That is the architecture of a basic MCP server.