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

---

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

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.