Skip to main content
Glama
kuldeeepy

first-mcp-server

by kuldeeepy
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

first-mcp-server

The smallest MCP server that actually does something — one tool, stdio transport, no build step. About 35 lines in server.ts.

I wrote this while figuring out how MCP works. If you've read Understanding MCP Servers, this is that post's weather example as code you can actually run.

What it does

Exposes a single tool, getCityWeather, over stdio. Ask Claude "what's the weather in Delhi?" and it discovers the tool, calls it, and answers from the result.

The weather itself is a hardcoded map of three cities. That's on purpose — the point here is the protocol, not the data. Swap the lookup for a real API call and nothing else about the server changes.

Related MCP server: fetch-weather

Run it

npm install
npm start

That starts the server on stdio. On its own it does nothing visible — it's waiting for a client to talk to it, which is the whole idea.

Connect it to Claude

Add it to your MCP config (claude_desktop_config.json for Claude Desktop, or .mcp.json for Claude Code):

{
  "mcpServers": {
    "first-server": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/first-mcp-server/server.ts"]
    }
  }
}

Use an absolute path — the host spawns this as a subprocess and won't be in your project directory. Restart the host, then ask it about the weather in Delhi, Mumbai or Bangalore.

The three pieces

Everything in server.ts is one of these:

Piece

What it is

McpServer

the server itself, with a name and version the client sees

registerTool

one tool — a name, a description, and an input schema

StdioServerTransport

how bytes move; JSON-RPC over stdin/stdout

The description and schema matter more than they look. They're the only thing the model reads when deciding whether this tool is relevant to your question, so vague descriptions produce a tool that never gets called.

License

MIT

Available Tools

1 tool
getCityWeatherB

Fetch the current weather for a city

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesCity name, e.g. Delhi

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations, the description alone carries the burden of behavioral disclosure. It states only that it fetches current weather and gives no context about data source, units (metric/imperial), response format, error handling for unknown cities, or whether the result is cached/real-time. This is a significant omission for a tool with no structured annotations.

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

Conciseness5/5

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

The description is a single, front-loaded sentence with zero redundant words. It conveys the core action efficiently and appropriately for such a simple tool.

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

Completeness3/5

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

For a tool with only one simple parameter and no output schema, the description is nearly sufficient. However, it lacks any note about what the response contains (e.g., temperature, humidity) or what happens if the city is not found, leaving a small but real gap for agent decision-making.

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 input schema fully documents the only parameter ('name') with a clear example ('City name, e.g. Delhi'), giving 100% schema coverage. The description merely echoes 'city' without adding format constraints or additional meaning, so the baseline of 3 is appropriate.

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 a clear verb ('Fetch') and a specific resource ('current weather for a city'), which unambiguously states what the tool does. Since there are no sibling tools, it doesn't need to differentiate itself, though it could have specified what weather attributes are returned.

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 provides no guidance on when to use this tool versus any alternative (none are listed). It doesn't mention any constraints like acceptable city name formats, typical use cases, or exclusivity with other weather methods.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.0.0
    • First observedgetCityWeather
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 or overlap. The single tool's purpose is immediately clear from its name and description.

Naming Consistency5/5

The single tool name follows a clear verb-noun camelCase pattern (getCityWeather), and there are no other names to create inconsistency.

Tool Count3/5

One tool feels thin for a weather server, which often supports forecasts, alerts, and other query types. It is not necessarily wrong, but it is on the low end of acceptable.

Completeness3/5

The tool covers the specific task of fetching current city weather, but leaves obvious gaps like forecasts, historical data, or unit selection unexplained. It is adequate for a narrow demo, but not a full weather service.

Maintenance

ActivityMaintained
ResponsivenessNo issues

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

  • Server MCP

    SeydinaBANE
    F
    license
    Not graded
    quality
    D
    maintenance
    Provides math and weather tools accessible via LangGraph agent using MCP protocol with stdio and streamable HTTP transports.
    1
    -

  • fetch-weather

    mishrole
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables users to get weather forecasts for any city using the Open-Meteo API through natural language in Claude Desktop or VS Code.
    -

  • Weather MCP Agent

    yehyaabk
    F
    license
    A
    quality
    B
    maintenance
    Provides current weather and forecast data for any city via OpenWeatherMap. Can be used with Ollama or Claude Desktop for natural-language weather queries.
    2
    -

  • Minimal MCP Demo

    ShashankEd
    F
    license
    B
    quality
    C
    maintenance
    This MCP server demonstrates basic Model Context Protocol architecture by exposing a get_weather tool that returns fake weather data, communicating over stdio.
    1
    -

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/kuldeeepy/first-mcp-server'

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