Skip to main content
Glama
mzoffoli85

MPC-PoC-1-EchoServerToolsbasicas

by mzoffoli85
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

PoC 1 — MCP Echo Server (Tools básicas sobre stdio)

Primera PoC de una serie de 5 para aprender MCP (Model Context Protocol) en profundidad. Server MCP en Python que expone 3 tools simples sobre transporte stdio, pensado para validar el handshake completo initialize → negociación de capabilities → tools/list → tools/call contra Claude Desktop / Claude Code.

Spec completa de la PoC: POC1_MCP_ECHO_SERVER.md.

Tools expuestas

Tool

Input

Output

Propósito didáctico

echo

message: str

el mismo string

Validar ida y vuelta trivial

add

a: float, b: float

la suma

Validar tipado de inputs y coerción

reverse

text: str

el string invertido

Validar manejo de strings no triviales

Implementadas como funciones síncronas y puras (sin efectos secundarios) usando la API moderna FastMCP del SDK mcp (decorador @mcp.tool()).

Related MCP server: node-mcp-poc

Instalar dependencias

Con uv (preferido):

uv sync

Con venv + pip:

python -m venv .venv
.venv\Scripts\activate      # Windows
pip install -e .

Registrar el server en Claude Desktop

Editar claude_desktop_config.json (en Windows: %APPDATA%\Claude\claude_desktop_config.json) y agregar:

{
  "mcpServers": {
    "poc1-echo-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\PoC\\MCP\\MPC-PoC-1-EchoServerToolsbasicas",
        "python",
        "server.py"
      ]
    }
  }
}

Si preferís usar el intérprete de un venv en vez de uv, reemplazá command/args por la ruta absoluta al python.exe del venv y ["C:\\PoC\\MCP\\MPC-PoC-1-EchoServerToolsbasicas\\server.py"].

Reiniciar Claude Desktop para que detecte el nuevo server.

Probar cada tool

Frases de ejemplo para gatillar cada tool desde el chat de Claude Desktop:

  • echo: "Usá la tool echo para repetir el mensaje 'hola mundo'"

  • add: "Sumá 15.5 y 22.3 usando la tool add"

  • reverse: "Invertí el string 'MCP' con la tool reverse"

También podés correr el server directo para validar que arranca sin errores:

python server.py

Va a quedar esperando input JSON-RPC por stdin (comportamiento normal); Ctrl+C para salir.

Ver los logs de stderr (debug del handshake)

Todo el logging va a stderr (nunca a stdout, que es el canal del protocolo). Claude Desktop guarda los logs de cada MCP server en:

%APPDATA%\Claude\logs\mcp-server-poc1-echo-server.log

Ahí se ve el initialize, la negociación de capabilities y cada tools/call con sus argumentos, gracias al logging agregado en server.py.

Qué aprendí

  • El SDK mcp moderno resuelve casi todo con FastMCP + @mcp.tool(): el schema de inputs se genera solo a partir de los type hints, sin tocar JSON Schema a mano.

  • El canal stdout está reservado 100% para JSON-RPC — cualquier print() o log mal dirigido rompe el protocolo; todo el logging tiene que ir a stderr explícitamente.

  • El handshake (initialize → tools/list → tools/call) es visible y depurable en los logs de Claude Desktop, lo cual hace mucho más fácil diagnosticar problemas de conexión que "adivinar" desde el lado del cliente.

  • Correr el server standalone (python server.py) antes de registrarlo en Claude Desktop ahorra un ciclo completo de debugging: si arranca limpio ahí, el problema de conexión está en la config, no en el código.

Siguiente en la serie

PoC 2 — Resource Provider: exponer Google Sheets como Resources leíbles vía MCP.

Available Tools

3 tools
addA

Suma dos numeros y devuelve el resultado.

ParametersJSON Schema
NameRequiredDescriptionDefault
aYes
bYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It states the core behavior and that it returns a result, but it does not discuss edge cases, error behavior, or side effects. Given the simplicity of the operation, this is adequate but not rich.

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?

One short sentence is front-loaded and contains no filler. 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 two-number addition tool with an output schema and no nested objects, the description is nearly complete. It clearly states inputs and the fact that a result is returned, though it omits trivial edge-case details.

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

Parameters2/5

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

Schema description coverage is 0%, so the description needed to compensate. It only says 'dos numeros', which restates the number types already in the schema without explaining the roles of a and b or any ordering concerns. The parameter names remain opaque.

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 the verb 'Suma' and the object 'dos numeros' to state exactly what the tool does. This clearly distinguishes it from sibling tools echo and reverse, which cover different operations.

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?

No guidance is given about when to choose add over alternatives. The description does not mention echo or reverse, nor any condition or context for using this tool, leaving the agent to infer.

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

echoA

Devuelve el mismo mensaje recibido, sin modificaciones.

ParametersJSON Schema
NameRequiredDescriptionDefault
messageYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations provided, the description must carry the transparency burden. It clearly discloses that the message is returned without modifications, which covers the core behavioral trait of an echo operation. It does not go into edge cases or error behavior, but none are essential for this simple 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?

A single, front-loaded sentence with no filler. It conveys the entire behavior efficiently and earns every word.

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 trivial one-parameter tool with an output schema present, the description is nearly complete: it identifies input, behavior, and result. It lacks explicit usage guidance, but the simplicity of the tool lowers the burden, so only a minor gap remains.

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?

Schema description coverage is 0%, so the description must compensate. It does by linking the single 'message' parameter to the returned value, clarifying that the parameter is the exact input echoed back. This adds semantic meaning beyond the bare schema property name and type.

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 states a specific verb ('Devuelve') and resource ('el mismo mensaje recibido'), making the tool's identity operation unmistakable. It also naturally distinguishes itself from siblings like 'reverse' and 'add' by emphasizing that no modification occurs.

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

Usage Guidelines3/5

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

The description implies the appropriate use case: invoke this tool when the exact original message must be returned unchanged. However, it does not explicitly mention alternatives or state when not to use this tool, leaving the guidance implicit rather than direct.

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

reverseB

Invierte el orden de los caracteres de un string.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior3/5

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

With no annotations, the description carries the full behavioral burden. It states the core operation, but does not clarify whether a new string is returned or the input is mutated, nor how Unicode or special characters are handled. The behavior is basically clear but under-specified.

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 with no filler, front-loaded with the action verb and a clear object. This is appropriately sized 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 one-parameter tool with an output schema, the description covers the essential operation, but it lacks explicit usage guidance relative to siblings and does not fully define the parameter. It is minimally adequate rather than robust.

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

Parameters2/5

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

The schema has 0% description coverage and the description only indirectly refers to 'un string' without naming the parameter `text`. With a single required parameter, the meaning is inferable, but the description does not explicitly compensate for the schema gap.

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 specific verb ('Invierte') and a concrete resource ('los caracteres de un string'), so the purpose is unambiguous. It does not explicitly mention siblings, but the operation is clearly distinct from echo and add.

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?

No guidance is given about when to use this tool versus echo or add. There are no stated conditions, prerequisites, or exclusions; usage must be inferred entirely from the name and the described operation.

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. 3 tool updatesv0.1.0
    • First observedadd
    • First observedecho
    • First observedreverse
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool performs a completely distinct operation: echo returns input unchanged, add performs numeric addition, reverse flips a string's character order. There is no overlap or ambiguity between them.

Naming Consistency5/5

All three tool names are single lowercase verbs in a consistent imperative style: echo, add, reverse. The pattern is uniform and predictable.

Tool Count4/5

Three tools is a reasonable size for a basic PoC utility server. While slightly minimal, it stays within a well-scoped range and avoids being either overly thin or bloated.

Completeness4/5

For a simple echo server with basic utilities, the set covers its apparent purpose without glaring gaps. The operations are self-contained, though there is no clear domain model requiring CRUD coverage.

Maintenance

ActivitySlowing
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

  • node-mcp-poc

    gurunate
    F
    license
    Not graded
    quality
    C
    maintenance
    A minimal MCP server that exposes tools for addition, echoing text, time lookup, and URL fetching, with support for HTTP and stdio transports.
    -

  • MCP Demo

    VictorC55
    F
    license
    Not graded
    quality
    C
    maintenance
    A model-agnostic MCP server exposing example tools (add1, multiply2, greet) for learning purposes, working with any LLM through stdio transport.
    -

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/mzoffoli85/MPC-PoC-1-EchoServerToolsbasicas'

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