Skip to main content
Glama
ShashankEd

Minimal MCP Demo

by ShashankEd
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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:

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

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.

Available Tools

1 tool
get_weatherC

Get a simple weather report for a city

ParametersJSON Schema
NameRequiredDescriptionDefault
cityYesCity name
countryNoOptional country code

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of disclosing behavior, but it only says 'simple weather report'. It does not reveal details such as units, error handling for invalid cities, data sources, or return structure, leaving significant behavioral transparency gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It is appropriately concise for a simple tool, though it could benefit from a bit more detail without harming conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of an output schema, the description should explain what the weather report contains, but it does not. The tool is simple, yet the absence of return-format details and behavioral context makes the description incomplete for an agent to confidently invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% coverage with descriptions for both parameters ('City name' and 'Optional country code'), so the baseline is 3. The description does not add any further parameter semantics beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'get' and identifies the resource as a 'weather report for a city', which clearly states the tool's function. However, the term 'simple' is vague, leaving ambiguity about whether it provides current conditions or forecasts, and there are no siblings to differentiate from.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or limitations. It merely states what the tool does, leaving the agent to infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0
Disambiguation5/5

Only one tool exists, so there is no possibility of confusion between tools. Each tool (the only tool) has a distinct purpose.

Naming Consistency5/5

The single tool name 'get_weather' follows a standard verb_noun convention, making the naming consistent by default.

Tool Count3/5

With just one tool, the set is on the thin side, but for a minimal demo this is acceptable; it falls into the borderline range for tool count.

Completeness5/5

The tool covers the single stated purpose of retrieving a weather report, so there are no obvious gaps for a simple read-only weather demo.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP Server Demo

    hxw-haha
    A
    license
    Not graded
    quality
    D
    maintenance
    A minimal Model Context Protocol server demo that exposes tools through HTTP API, including greeting, weather lookup, and HTTP request capabilities. Demonstrates MCP server implementation with stdio communication and HTTP gateway functionality.
    10
    ISC

  • ai-mcp

    wangyj641
    F
    license
    A
    quality
    D
    maintenance
    Lightweight MCP server that exposes tools for system information and weather lookup, designed for agent integration via stdio.
    1

  • MCP Server

    Sandeep-Petwal
    A
    license
    Not graded
    quality
    D
    maintenance
    This MCP server provides tools like weather lookup and follows the Model Context Protocol for tool calling, resource sharing, and prompt templates.
    225
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ShashankEd/demo-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server