toy-mcp-server

Un servidor mínimo de Model Context Protocol (MCP) construido desde cero para aprender cómo funciona MCP de verdad: sin generadores de boilerplate, sin plantillas, solo el SDK.

Creado como primer proyecto práctico de MCP: dos herramientas y un recurso, conectados a Claude Desktop mediante stdio.

Qué hace

MCP permite que un cliente LLM (como Claude Desktop) llame a funciones que se ejecutan en tu propia máquina, en lugar de limitarse a generar texto a partir de sus datos de entrenamiento. Este servidor expone:

Herramientas (funciones que Claude puede llamar):

• roll_dice — lanza N dados con un número configurable de caras

• flip_coin — lanza una moneda al aire N veces

Recursos (datos de solo lectura que Claude puede solicitar):

• server-info — metadatos básicos del servidor (nombre, propósito, hora de inicio)

Por qué existe

Los LLM no pueden acceder a nada más allá de sus propios datos de entrenamiento y, por defecto, no pueden hacer nada: solo generar texto. MCP es una forma estándar de dar al modelo:

• capacidad que no tiene por sí solo (p. ej. la aleatoriedad real: los LLM son notoriamente malos eligiendo números aleatorios)

• acceso a datos actualizados, a pool de datos o privados que no tiene manera de conocer

Este proyecto es un sandbox pequeño y seguro para esa idea antes de llevar un servidor MCP a un recurso real (una base de datos, una API con autenticación, etc.)

Tecnologías utilizadas

• TypeScript

• @modelcontextprotocol/sdk — SDK oficial de MCP

• zod — validación de esquemas para los argumentos de las herramientas

• transporte stdio (comunicación local por subproceso con Claude Desktop)

Estructura del proyecto

toy-mcp-server/
├── src/
│   └── index.ts       # server setup, tools, and resource
├── build/              # compiled output (git-ignored)
├── package.json
├── tsconfig.json
└── README.md

Configurar

1. Instalar los dependencias

npm install

2. Compilar

npm run build

3. Conectar con Claude Desktop

Encuentra el archivo de configuración de Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: normalmente en %LOCALAPPDATA%\Packages\<Claude package folder>\LocalCache\Roaming\Claude\claude_desktop_config.json; la ruta exacta puede variar según el método de instalación (Microsoft Store en comparación con el instalador directo). La forma fiable de encontrarlo es: abre Claude Desktop → Configuracióndesarrollador → Servidores MCP locales → Editar configuración, que abre el archivo exacto que la aplicación lee.

Añade este servidor bajo mcpServers (combínalo con el archivo existente en lugar de sobrescribirlo):

{
  "mcpServers": {
    "toy-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/toy-mcp-server/build/index.js"]
    }
  }
}

Reemplaza la ruta por la ruta absoluta real hasta build/index.js en tu máquina.

Windows: escapa las barras invertidas de la ruta dentro de la cadena JSON.

4. Reiniciar Claude Desktop

Sal de Claude Desktop por completo (no solo cierra la ventana) y vuelve a abrirlo. Ve a ConfiguraciónDesarrollador → Servidores MCP locales para confirmar que toy aparece como conectado. toy-mcp-server aparece como conectado.

5. Prueba y

En un chat, pide por ejemplo:

• "Tira 3 dados de seis caras"

• "Lanza una moneda 10 veces"

Deberías ver un pequeño indicador de llamada a la herramienta (por ejemplo, "Roll Dice") junto a la marca final, comprobando que Claude ha invocado la función de verdad en lugar de adivinar la respuesta.

Cómo funciona, en breve

• McpServer — el objeto que declara las capacidades del servidor ante cualquier cliente que se conecte

• registerTool(name, config, handler) — registra una función que se puede llamar. config.inputSchema usa Zod para validar los argumentos que el modelo envíe el servidor con el fin de que se ejecute el handler

• registerResource(name, uri, config, handler) — registra datos de solo lectura más direccionados por una URI, que se recuperan estén eternados sin argumentos

• StdioServerTransport — la fuente de conexión: Claude Desktop lanza el archivo como un subproceso y se comunica con él a través de stdin/stdout usando JSON-RPC. console.log nunca se usa aquí para registrar, ya que stdout es el canal real del protocolo; en su lugar por defecto se usa console.error (estderr).

Próximos pasos

• Cambia los webs de juguete por otros reales que conecten con una base de datos real (postgres vía Prisma)

• Añade una herramienta con respaldo de GitHub (p. ej. list_open_prs) para practicar con autenticación por token

• Explora una sinta el transporte Streamable HTTP para subir este servidor de forma remota, en lugar de ejecutarlo localmente

Licencia

MIT