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:

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"],
});

Request flow

Here is the full flow in one simple sequence:

Client launches the server
Client sends tools/call for get_weather
Server receives the request
Server runs the tool function
Server returns text + JSON data
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

Pattern	Normal app	MCP app
Transport	HTTP / REST	stdio or streamable HTTP
Server role	Service	Tool provider
Lifecycle	Long-running service	Often started on demand
Main purpose	Business API	Expose actions to an AI client

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.