Quickstart

# TypeScript / Node
npm install @modelcontextprotocol/server @modelcontextprotocol/express @modelcontextprotocol/node express zod

# Python
uv add "mcp[cli]"     # o: pip install "mcp[cli]"

import { McpServer } from '@modelcontextprotocol/server';
import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
import { createMcpExpressApp } from '@modelcontextprotocol/express';
import * as z from 'zod/v4';

const server = new McpServer({ name: 'acme-tools', version: '1.0.0' });

server.registerTool(
  'consultar_cliente',
  {
    description:
      'Busca un cliente por número de documento y devuelve sus datos de contacto y estado. ' +
      'Úsala para identificar a quién se está atendiendo. No la uses para modificar datos.',
    inputSchema: z.object({
      documento: z.string().min(5).max(20),
    }),
  },
  async ({ documento }) => {
    const cliente = await miBackend.buscarCliente(documento); // su API actual

    if (!cliente) {
      return {
        content: [{ type: 'text', text: 'No encontré un cliente con ese documento.' }],
        structuredContent: { encontrado: false },
      };
    }

    return {
      content: [{ type: 'text', text: `Cliente ${cliente.nombre}, estado ${cliente.estado}.` }],
      structuredContent: {
        encontrado: true,
        nombre: cliente.nombre,
        estado: cliente.estado,
        telefono: cliente.telefono,
      },
    };
  },
);

const app = createMcpExpressApp();

app.post('/mcp', async (req, res) => {
  // Sin estado: un transporte por petición. Es el modo que exige el Gateway.
  const transport = new NodeStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(8080);

from mcp.server import MCPServer

mcp = MCPServer("acme-tools")


@mcp.tool()
def consultar_cliente(documento: str) -> dict:
    """Busca un cliente por documento y devuelve sus datos de contacto y estado.

    Úsala para identificar a quién se está atendiendo. No la uses para modificar datos.
    """
    cliente = mi_backend.buscar_cliente(documento)
    if cliente is None:
        return {"encontrado": False}
    return {
        "encontrado": True,
        "nombre": cliente.nombre,
        "estado": cliente.estado,
        "telefono": cliente.telefono,
    }

uv run mcp dev server.py     # Python; abre el MCP Inspector

import pytest
from mcp import Client

from server import mcp


@pytest.mark.anyio
async def test_consultar_cliente() -> None:
    async with Client(mcp) as client:
        result = await client.call_tool("consultar_cliente", {"documento": "CC1032"})
        assert result.structured_content["encontrado"] is True