How do I use MCP Learning Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Learning Server Give me a random quote" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Learning Server

by somyabhadada

Overview Schema Related Servers Score Discussions

Python

Local

🔌 MCP Learning Project

A complete educational project demonstrating the Model Context Protocol (MCP) end-to-end.

This project is designed for developers who are completely new to MCP and want to understand:

What an MCP Server is
What an MCP Client is
How they communicate
How tools are registered and discovered
How requests flow and responses return

📋 Table of Contents

Related MCP server: MCP Server Basic Example

🎯 Project Overview

This project implements:

Component	Description
MCP Server	A FastMCP server exposing 5 tools via stdio transport
Interactive Client	A Rich-powered CLI that discovers and calls tools
Chat Interface	A natural language chatbot that maps queries to tools
Pydantic Validation	Type-safe input validation with friendly errors
Logging	Structured logs with INFO/WARNING/ERROR levels
Architecture Diagrams	Mermaid diagrams explaining every component

Tech Stack

Python 3.11+
uv package manager
Official MCP Python SDK (mcp[cli] with FastMCP)
asyncio
Pydantic v2
Rich library

🏗️ Architecture

High-Level Architecture

┌─────────────────────┐          ┌─────────────────────┐
│     MCP Client      │   stdio  │     MCP Server      │
│                     │◄────────►│                     │
│  • Rich CLI/Chat    │  JSON-   │  • FastMCP Router   │
│  • ClientSession    │  RPC 2.0 │  • 5 Registered     │
│  • Tool Discovery   │          │    Tools            │
└─────────────────────┘          └─────────────────────┘

Request Flow

User
 ↓
Client UI (Rich terminal)
 ↓
ClientSession.call_tool(name, arguments)
 ↓
JSON-RPC 2.0 Request (serialized)
 ↓
stdio Transport (stdin pipe to server subprocess)
 ↓
FastMCP Server (deserializes, routes by tool name)
 ↓
@mcp.tool() Function → Pydantic validation → Business logic
 ↓
JSON Response (consistent format)
 ↓
stdio Transport (stdout pipe back to client)
 ↓
ClientSession (deserializes response)
 ↓
Rich UI (pretty-prints with syntax highlighting)
 ↓
User sees the result ✅

Tool Discovery Flow

Client                          Server
  |                               |
  |──── initialize() ───────────►|
  |◄──── capabilities ──────────|
  |                               |
  |──── list_tools() ───────────►|
  |◄──── tool schemas ──────────|
  |       (name, description,     |
  |        inputSchema)           |
  |                               |
  |  Client now knows all tools!  |

📌 Key MCP advantage: The client doesn't need hardcoded endpoints. It discovers tools dynamically!

📁 Folder Structure

mcp-learning-project/
│
├── server/                    # MCP Server (the "backend")
│   ├── __init__.py           # Package marker
│   ├── server.py             # FastMCP setup + tool registration
│   ├── tools.py              # Pure business logic (no MCP dependency)
│   ├── models.py             # Pydantic validation models
│   └── quotes.py             # Hardcoded quote data
│
├── client/                    # MCP Client (the "frontend")
│   ├── __init__.py           # Package marker
│   ├── client.py             # Interactive CLI client
│   ├── chat.py               # Natural language chat interface
│   └── ui.py                 # Rich terminal UI helpers
│
├── diagrams/                  # Documentation
│   └── architecture.md       # Mermaid architecture diagrams
│
├── logs/                      # Generated at runtime
│   └── app.log               # Structured application logs
│
├── screenshots/               # Screenshots placeholder
│
├── README.md                  # This file
├── pyproject.toml            # Project configuration
├── uv.lock                   # Dependency lock file (auto-generated)
└── .gitignore                # Git ignore rules

Why Each File Exists

File	Purpose
`server/server.py`	MCP registration layer — connects business logic to the MCP protocol using `@mcp.tool()` decorators
`server/tools.py`	Business logic — pure Python functions that can be tested without MCP
`server/models.py`	Validation — Pydantic models that enforce type safety at the input boundary
`server/quotes.py`	Data — separates data from logic for clean architecture
`client/client.py`	Interactive client — demonstrates the full MCP client workflow
`client/chat.py`	Chat interface — shows how natural language maps to tool calls
`client/ui.py`	Presentation — all Rich formatting in one place

🚀 Installation

Prerequisites

Python 3.11 or higher
uv package manager

Setup

# 1. Clone the repository
git clone <repository-url>
cd mcp-learning-project

# 2. Create a virtual environment and install dependencies
uv sync

# This will:
# - Create a .venv/ directory
# - Install mcp[cli], pydantic, and rich
# - Generate uv.lock for reproducibility

▶️ Running the Project

Option 1: Interactive Client (Recommended)

The client automatically starts the server as a subprocess — you only need one terminal:

uv run python -m client.client

Option 2: Chat Interface

uv run python -m client.chat

Option 3: Server Only (for debugging)

If you want to run the server independently (e.g., to test with MCP Inspector):

uv run python -m server.server

⚠️ The server uses stdio transport, so it reads from stdin and writes to stdout. Running it directly will wait for JSON-RPC input — this is expected behavior.

Testing with MCP Inspector

The MCP Inspector is a visual debugging tool:

npx -y @modelcontextprotocol/inspector uv run python -m server.server

🧰 Available Tools

1. `current_time`

Returns the current UTC time in ISO 8601 format.


Input	None
Output	`{"success": true, "data": {"current_time": "2026-07-01T12:00:00Z"}}`

2. `calculator`

Performs arithmetic operations on two numbers.


Input	`{"a": 10, "b": 20, "operation": "add"}`
Operations	`add`, `subtract`, `multiply`, `divide`
Output	`{"success": true, "data": {"result": 30.0}}`
Division by zero	`{"success": false, "error": "Division by zero is not allowed"}`

3. `random_quote`

Returns a random inspirational quote from an internal list of 25 quotes.


Input	None
Output	`{"success": true, "data": {"quote": "Stay hungry, stay foolish. — Steve Jobs"}}`

4. `weather`

Returns mock weather data for Indian cities.


Input	`{"city": "Jaipur"}`
Supported Cities	Jaipur, Delhi, Mumbai, Bangalore, Chennai, Kolkata, Hyderabad, Pune
Output	`{"success": true, "data": {"city": "Jaipur", "temperature": "35°C", "condition": "Sunny"}}`
Unknown city	`{"success": false, "error": "City 'London' not found. Available cities: ..."}`

5. `uuid_generator`

Generates a random UUID (version 4).


Input	None
Output	`{"success": true, "data": {"uuid": "550e8400-e29b-41d4-a716-446655440000"}}`

💻 Example Execution

Interactive Client

╭─────────────────────────────────────────────╮
│ 🔌 MCP Learning Client                     │
│    Connected to MCP Server via stdio        │
╰─────────────────────────────────────────────╯

┌──────────────────────────────────────────────┐
│            📋 Available Tools                │
├────┬────────────────┬────────────────────────┤
│ #  │ Tool Name      │ Description            │
├────┼────────────────┼────────────────────────┤
│ 1  │ current_time   │ Get the current UTC    │
│    │                │ time in ISO 8601       │
├────┼────────────────┼────────────────────────┤
│ 2  │ calculator     │ Perform arithmetic     │
│    │                │ operations             │
├────┼────────────────┼────────────────────────┤
│ 3  │ random_quote   │ Get a random           │
│    │                │ inspirational quote    │
├────┼────────────────┼────────────────────────┤
│ 4  │ weather        │ Get mock weather data  │
├────┼────────────────┼────────────────────────┤
│ 5  │ uuid_generator │ Generate a random UUID │
└────┴────────────────┴────────────────────────┘

>>> 2
Enter calculator inputs:
  First number (a): 45
  Second number (b): 87
  Operation (add/subtract/multiply/divide): multiply
⏳ Calling calculator...
╭─── ✅ Success ───╮
│ {                │
│   "result": 3915 │
│ }                │
╰──────────────────╯
⏱  Completed in 0.023s

>>> info weather
📌 weather

Get mock weather data for an Indian city.

📥 Input Schema:
{
  "type": "object",
  "properties": {
    "city": { "type": "string" }
  },
  "required": ["city"]
}

>>> exit
👋 Goodbye!

Chat Interface

🤖 MCP Chat Interface
Ask me about weather, calculations, time, quotes, or UUIDs.
Type 'exit' to quit.

You: What is the weather in Jaipur?
⏳ Calling weather tool...
╭─── 🤖 Assistant ───╮
│ 🌤️  Weather in      │
│ Jaipur: 35°C, Sunny │
╰─────────────────────╯

You: Multiply 45 and 87
⏳ Calling calculator tool...
╭─── 🤖 Assistant ───╮
│ 🔢 The answer is:   │
│ 3915.0               │
╰─────────────────────╯

You: Give me an inspirational quote
⏳ Calling random_quote tool...
╭───── 🤖 Assistant ─────╮
│ 💬 "Stay hungry, stay   │
│ foolish. — Steve Jobs"  │
╰─────────────────────────╯

Example Log Output (`logs/app.log`)

2026-07-08 10:30:15 | INFO    | mcp.server | FastMCP server instance created: 'MCP Learning Server'
2026-07-08 10:30:15 | INFO    | mcp.server | Starting MCP Learning Server (stdio transport)...
2026-07-08 10:30:16 | INFO    | mcp.client | Client starting — connecting to MCP server...
2026-07-08 10:30:16 | INFO    | mcp.client | stdio transport established
2026-07-08 10:30:16 | INFO    | mcp.client | MCP session initialized
2026-07-08 10:30:16 | INFO    | mcp.client | Discovered 5 tools: ['current_time', 'calculator', ...]
2026-07-08 10:30:20 | INFO    | mcp.client | Calling tool: calculator with args: {'a': 45, 'b': 87, 'operation': 'multiply'}
2026-07-08 10:30:20 | INFO    | mcp.server | Tool called: calculator(a=45.0, b=87.0, op=multiply)
2026-07-08 10:30:20 | INFO    | mcp.server | Tool result: calculator → {'success': True, 'data': {'result': 3915.0}}
2026-07-08 10:30:20 | INFO    | mcp.client | Tool calculator completed in 0.023s

📚 MCP Learning Notes

What is MCP?

The Model Context Protocol (MCP) is a standardized protocol for connecting AI models to external tools and data sources. Think of it as a "USB-C for AI" — a universal interface that lets any AI assistant use any tool without custom integrations.

How MCP Registers Tools

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My Server")

@mcp.tool(
    name="calculator",
    description="Perform arithmetic operations"
)
def calculator(a: float, b: float, operation: str) -> str:
    # FastMCP auto-generates a JSON Schema from the function signature:
    # {
    #   "type": "object",
    #   "properties": {
    #     "a": {"type": "number"},
    #     "b": {"type": "number"},
    #     "operation": {"type": "string"}
    #   },
    #   "required": ["a", "b", "operation"]
    # }
    ...

When @mcp.tool() is called:

FastMCP inspects the function's type hints
Generates a JSON Schema for the inputs
Stores the tool in an internal registry
When list_tools() is called, returns all registered schemas

How the Client Discovers Tools

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# 1. Define how to launch the server
server_params = StdioServerParameters(
    command="uv",
    args=["run", "python", "-m", "server.server"]
)

# 2. Connect via stdio
async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # 3. Initialize the session (handshake)
        await session.initialize()

        # 4. Discover all tools
        tools = await session.list_tools()
        # tools.tools → list of Tool objects with name, description, inputSchema

        # 5. Call a specific tool
        result = await session.call_tool("calculator", {"a": 10, "b": 20, "operation": "add"})

How Requests are Serialized

MCP uses JSON-RPC 2.0 over the stdio transport:

// Client → Server (request)
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "calculator",
    "arguments": {"a": 10, "b": 20, "operation": "add"}
  }
}

// Server → Client (response)
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"success\": true, \"data\": {\"result\": 30.0}}"
      }
    ]
  }
}

How Transport Works

This project uses stdio transport:

The client spawns the server as a subprocess
JSON-RPC messages flow through the subprocess's stdin (requests) and stdout (responses)
This is why we never print() to stdout in the server — it would corrupt the protocol!

Other MCP transports include:

SSE (Server-Sent Events): HTTP-based, good for remote servers
Streamable HTTP: Newer HTTP transport for production use

How MCP Differs from REST

Aspect	REST API	MCP
Discovery	You need documentation/OpenAPI spec	`list_tools()` returns schemas dynamically
Protocol	HTTP request/response	JSON-RPC 2.0 (bidirectional)
Schema	OpenAPI (optional)	JSON Schema (built-in)
Transport	Always HTTP	stdio, SSE, Streamable HTTP
Standardization	Varies per API	One protocol for all tools
AI Integration	Custom per model	Universal — any model, any tool

How to Add a New Tool

Adding a tool takes 3 steps:

Business logic — Add a function to server/tools.py:

def my_tool(input_param: str) -> dict[str, Any]:
    """Do something useful."""
    return ToolResponse.ok(result="Hello!")

Validation (optional) — Add a Pydantic model to server/models.py:

class MyToolInput(BaseModel):
    input_param: str = Field(..., min_length=1)

Registration — Add a @mcp.tool() decorator in server/server.py:

@mcp.tool(name="my_tool", description="Does something useful")
def tool_my_tool(input_param: str) -> str:
    return json.dumps(my_tool(input_param))

That's it! The client will auto-discover the new tool on next connection.

⚠️ Common Errors

Error	Cause	Solution
`Server script not found`	Running from wrong directory	`cd` to project root
`ModuleNotFoundError: server`	Missing `uv sync` or wrong Python	Run `uv sync` first
`ConnectionError`	Server failed to start	Check `logs/app.log` for details
`Invalid operation`	Typo in operation name	Use: add, subtract, multiply, divide
`Division by zero`	b=0 with divide operation	Expected — handled gracefully
`City not found`	City not in mock data	Use: Jaipur, Delhi, Mumbai, Bangalore, Chennai, Kolkata
`Broken pipe` / garbled output	Printing to stdout in server	Always use logging or stderr

🔮 Future Improvements

Add LLM integration for intelligent intent parsing
Implement SSE transport for remote server access
Add tool caching and rate limiting
Build a web-based UI alongside the CLI
Add unit tests for each tool
Implement MCP Resources and Prompts (beyond Tools)
Add authentication and authorization
Create a tool that chains multiple other tools

📄 License

MIT License — Feel free to use this for learning and education.

Built as an educational project to understand the Model Context Protocol (MCP).

Available Tools

5 tools

calculatorA

Perform arithmetic operations on two numbers. Supported operations: add, subtract, multiply, divide.

ParametersJSON Schema

Name	Required	Description	Default
`a`	Yes
`b`	Yes
`operation`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

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

No annotations provided, so description carries full burden. It describes supported operations but omits edge cases like division by zero or input validation. Basic transparency but not comprehensive.

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?

Single sentence with no redundancy. Front-loaded key info (purpose and operations). Every word earns its place.

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

Completeness4/5

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

For a simple tool with output schema, description covers purpose and supported operations. Could mention error handling or output details for full completeness, but it is largely sufficient.

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?

Schema has 0% description coverage. Description mentions 'two numbers' and 'supported operations' but does not specify exact string values for operation (e.g., 'add', '+'). Adds some meaning beyond schema but lacks precision.

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

Purpose5/5

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

Description clearly states it performs arithmetic operations on two numbers and lists supported operations. The name 'calculator' reinforces this, and sibling tools are unrelated, making its purpose distinct.

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

Usage Guidelines4/5

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

Clear context for usage: arithmetic operations. While no explicit when-not or alternatives given, sibling tools are clearly different, so an agent can infer appropriate use.

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

current_timeA

Get the current UTC time in ISO 8601 format. No input required.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

With no annotations provided, the description takes full responsibility. It discloses the output format (ISO 8601) and the timezone (UTC), which is sufficient for this read-only, non-destructive tool. No hidden behaviors are implied.

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 two short, direct sentences. Every word is necessary and front-loaded with the key purpose. No verbose or redundant content.

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

Completeness5/5

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

Given the tool's simplicity (no parameters, has output schema), the description is fully complete. It specifies the timezone, format, and that no input is needed. No additional context is required.

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

Parameters4/5

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

There are zero parameters, so the baseline is 4. The description correctly notes 'No input required,' adding no unnecessary parameter information. No schema details to compensate for.

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

Purpose5/5

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

The description clearly states the tool's function: 'Get the current UTC time in ISO 8601 format.' It uses a specific verb ('Get') and resource ('current UTC time'), and it is distinct from sibling tools like calculator or weather.

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

Usage Guidelines4/5

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

The description explicitly says 'No input required,' guiding the agent on invocation. While it doesn't mention when not to use it, the tool is self-contained and has no obvious alternatives among siblings.

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

random_quoteA

Get a random inspirational quote. No input required.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

The description discloses that the tool returns an inspirational quote and requires no input. Since no annotations are provided, the description carries full burden and does so adequately, though it could mention if the quote is truly random or fetched from a source.

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 extremely concise, using only two sentences with no unnecessary words. It front-loads the main action and resource, and every word earns its place.

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

Completeness4/5

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

The tool is simple with no parameters and a clear purpose. An output schema exists but is not described; however, for a random quote tool, the return format is likely obvious. The description is complete enough for use.

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

Parameters4/5

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

There are no parameters, and the schema coverage is 100%. The description correctly notes 'No input required,' so no additional parameter information is needed.

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

Purpose5/5

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

The description clearly states the tool gets a random inspirational quote, and the sibling tools (calculator, current_time, etc.) are all different in functionality, so there is no ambiguity.

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

Usage Guidelines4/5

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

The description explicitly states 'No input required,' which implies the tool is ready to use without preparation. However, it does not explicitly say when to use it versus alternatives, but given the unique purpose, it is sufficient.

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

uuid_generatorA

Generate a random UUID (version 4). No input required.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior3/5

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

With no annotations, the description provides basic behavior (random, version 4) but does not detail output format or any side effects. An output schema exists to supplement.

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 sentence that is front-loaded and contains no unnecessary words.

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

Completeness5/5

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

The description is complete given the tool's simplicity: no parameters, and an output schema likely defines the return value.

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

Parameters4/5

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

There are no parameters, and the description explicitly states 'No input required,' which is sufficient. Baseline 4 for 0 parameters with full schema coverage.

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

Purpose5/5

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

The description clearly states the tool generates a random UUID (version 4) with no input, which is specific and distinct from sibling tools like calculator or weather.

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

Usage Guidelines4/5

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

The description indicates that no input is needed, implying straightforward usage. It does not explicitly discuss when not to use, but the simplicity makes it clear.

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

weatherA

Get mock weather data for an Indian city. Supported cities: Jaipur, Delhi, Mumbai, Bangalore, Chennai, Kolkata, Hyderabad, Pune.

ParametersJSON Schema

Name	Required	Description	Default
`city`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior3/5

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

No annotations are present, so the description carries the full behavioral burden. It discloses the mock nature of the data but lacks details about error handling, rate limits, or what happens with unsupported cities. A 3 is adequate for a simple read tool.

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 consists of two concise, front-loaded sentences. Every sentence adds value—the first states the tool's purpose, the second provides actionable city options.

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

Completeness5/5

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

Given the output schema exists, return values are documented. The tool is simple with one required parameter and no nested objects. The description fully covers usage context with the city list.

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?

Schema coverage is 0%, so the description must compensate. It implicitly covers the 'city' parameter by listing supported cities, adding meaning beyond the schema's bare type. However, it doesn't explain parameter format or optional details.

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

Purpose5/5

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

The description uses a specific verb 'Get' and resource 'mock weather data' with a clear scope 'for an Indian city'. It distinguishes itself from siblings (calculator, current_time, etc.) which are unrelated.

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

Usage Guidelines4/5

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

The description lists supported cities, providing context. No explicit when-to-use or when-not-to-use is needed since siblings are unrelated. A score of 4 reflects clear context without exclusions.

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.

5 tool updatesv1.0.0Jul 8, 2026
- First observedcalculator
- First observedcurrent_time
- First observedrandom_quote
- First observeduuid_generator
- First observedweather

Install Server

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

TDQS

A4.4/5.0

Disambiguation5/5

Each tool serves a distinct purpose: calculator for arithmetic, current_time for time, random_quote for quotes, uuid_generator for UUIDs, and weather for mock weather data. There is no overlap or ambiguity.

Naming Consistency5/5

All tool names are lowercase, descriptive, and use underscores where needed. They follow a consistent pattern of terse but clear naming.

Tool Count5/5

With 5 tools, the set is well-scoped for a learning/demo server. Each tool provides a distinct utility without being overwhelming or too sparse.

Completeness4/5

The set covers several typical utility functions (math, time, random, identification, weather). A minor gap could be string manipulation or unit conversion, but for a learning server it is adequately complete.

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Related MCP Connectors

staging-mcpOAuth
dev.riskprofiler
An MCP server that provides a hello tool
1
test-mcp B
dev.riskprofiler
An MCP server that provides a hello tool
11
PlanExe A
io.github.PlanExeOrg
MCP server for generating rough-draft project plans from natural-language prompts.
Autonomous Agents Developer Tools Project Management
113398
strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748

Related MCP Servers

Minimal MCP
Developer Tools Education & Learning Tools
engineers-hub-ltd-in-house-project
F
license
Not graded
quality
D
maintenance
A basic educational MCP server that provides simple tools for mathematical calculations, text manipulation, and time retrieval. Designed for learning MCP implementation patterns and development purposes.
Updated a year ago (2025-08-24 02:28 UTC)
-
MCP Server Basic Example
Weather Services Developer Tools
dorisashehi
-
license
Not graded
quality
Not graded
maintenance
A basic Model Context Protocol server implementation that demonstrates core MCP functionality including tools and resources. Provides weather alerts through the Weather API and serves as a learning example for MCP development.
Updated a year ago (2025-09-15 02:27 UTC)
-
simple_mcp
Developer Tools Education & Learning Tools
halisyilboga
F
license
Not graded
quality
D
maintenance
An educational MCP server that teaches implementing the Model Context Protocol from scratch, enabling AI models to discover and invoke tools via JSON-RPC over stdio.
Updated 4 months ago (2026-05-10 00:40 UTC)
-
Demo MCP Server
Developer Tools Education & Learning Tools
hellozexi
F
license
Not graded
quality
D
maintenance
A learning-purpose MCP server providing tools for arithmetic calculation, current time retrieval, and text analysis.
Updated 8 months ago (2026-01-13 14:28 UTC)
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/somyabhadada/mcp_server'

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

🔌 MCP Learning Project

📋 Table of Contents

🎯 Project Overview

Tech Stack

🏗️ Architecture

High-Level Architecture

Request Flow

Tool Discovery Flow

📁 Folder Structure

Why Each File Exists

🚀 Installation

Prerequisites

Setup

▶️ Running the Project

Option 1: Interactive Client (Recommended)

Option 2: Chat Interface

Option 3: Server Only (for debugging)

Testing with MCP Inspector

🧰 Available Tools

1. current_time

2. calculator

3. random_quote

4. weather

5. uuid_generator

💻 Example Execution

Interactive Client

Chat Interface

Example Log Output (logs/app.log)

📚 MCP Learning Notes

What is MCP?

How MCP Registers Tools

How the Client Discovers Tools

How Requests are Serialized

How Transport Works

How MCP Differs from REST

How to Add a New Tool

⚠️ Common Errors

🔮 Future Improvements

📄 License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

1. `current_time`

2. `calculator`

3. `random_quote`

4. `weather`

5. `uuid_generator`

Example Log Output (`logs/app.log`)