≡En resumen
- Antes de programar, decide qué tareas concretas resolverá la IA y qué herramientas mínimas necesita para hacerlas.
- Un servidor MCP ofrece tres tipos de capacidades: herramientas (tools), recursos (resources) y prompts.
- Hay SDK oficiales para TypeScript, Python, C#, Go, Rust, Ruby, Java, Swift, PHP y Kotlin; en Laravel tienes el paquete laravel/mcp.
- MCP Inspector es la herramienta de referencia para probar el servidor antes de conectarlo a Claude o ChatGPT.
- Un servidor remoto que actúa sobre datos de tus usuarios necesita OAuth 2.1, permisos por usuario y confirmación antes de escribir.
01 Antes de crear un servidor MCP: casos de uso, herramientas y local o remoto
Un servidor MCP es un programa que habla el Model Context Protocol y le ofrece a una aplicación de IA (Claude, ChatGPT, Copilot, Cursor y otros clientes compatibles) acciones y datos de tu sistema. Si todavía no tienes claro qué es MCP y para qué sirve, empieza por ahí: este artículo da por hecho el concepto y va directo a construir.
El error más caro no es de código, es de enfoque: abrir el SDK y convertir cada endpoint de tu API REST en una herramienta. Antes de escribir una línea, responde a tres preguntas.
- ✓¿Qué tareas concretas quieres que la IA haga con tu sistema? Escribe cinco o seis frases reales de usuario, por ejemplo «¿qué facturas de Acme siguen pendientes?».
- ✓¿Qué herramientas mínimas resuelven esas frases? Normalmente son pocas y orientadas a tareas, no una por tabla o endpoint.
- ✓¿Qué herramientas solo leen y cuáles crean, modifican o borran? Las de escritura necesitarán permisos y confirmación.
- ✓¿Quién lo va a usar? Solo tú en tu ordenador, tu equipo o tus clientes, cada uno con su cuenta.
- ✓¿Dónde viven los datos? En archivos locales, en una base de datos interna o detrás de una API en la nube.
| Aspecto | Local (stdio) | Remoto (Streamable HTTP) |
|---|---|---|
| Cómo se ejecuta | El cliente lanza el servidor como un proceso en tu máquina | Vive en un servidor y el cliente se conecta por una URL HTTPS |
| Para quién | Una persona: herramientas personales, archivos locales, desarrollo | Equipos y clientes: cada usuario se conecta con su cuenta |
| Autenticación | Credenciales en variables de entorno | OAuth 2.1 según la especificación de autorización de MCP |
| Clientes | Apps de escritorio y herramientas de desarrollo como Claude Code o Cursor | También los clientes web, como Claude o ChatGPT en el navegador |
| Despliegue | Nada que desplegar: se instala en cada equipo | Hosting, dominio, HTTPS, logs y mantenimiento |
02 Anatomía de un servidor MCP: tools, resources y prompts
La especificación define tres tipos de capacidades que un servidor puede ofrecer. La mayoría de servidores empiezan solo con herramientas, pero conviene conocer las tres para elegir bien dónde va cada cosa.
Tools (herramientas)
Funciones que el modelo decide llamar: buscar un cliente, crear un presupuesto, consultar el stock. Las controla el modelo, siempre con la posibilidad de que una persona las deniegue.
Resources (recursos)
Datos y contexto que el cliente puede leer, identificados por una URI: un documento, una ficha, un catálogo. Sirven para aportar información sin ejecutar ninguna acción.
Prompts
Plantillas de mensajes o flujos pensados para el usuario, por ejemplo «prepara el resumen semanal de incidencias». El usuario los elige; no los dispara el modelo por su cuenta.
| Campo | Qué es | Consejo |
|---|---|---|
| name | Identificador único dentro del servidor | Verbo y objeto, sin espacios: buscar_factura, crear_presupuesto |
| title | Nombre legible para mostrar (opcional) | Lo que verá el usuario en la interfaz |
| description | Explicación de lo que hace la herramienta | Es lo que lee el modelo para decidir cuándo usarla: cuándo sí, cuándo no y qué devuelve |
| inputSchema | JSON Schema de los parámetros de entrada | Tipos, campos obligatorios, enumeraciones y una descripción por parámetro |
| outputSchema | JSON Schema del resultado estructurado (opcional) | Útil cuando otro programa o el modelo necesita datos con forma fija |
| annotations | Pistas de comportamiento: solo lectura, destructiva, idempotente | Márcalas bien, pero no las uses como medida de seguridad: los clientes las tratan como no fiables |
03 Elige lenguaje y SDK oficial
No implementes el protocolo a mano: usa un SDK oficial. Se encargan de los mensajes, la negociación de versión y los transportes, y te dejan centrarte en las herramientas. La documentación de MCP los clasifica por niveles según lo completos que están y el compromiso de mantenimiento.
| Nivel | Lenguajes | Cuándo elegirlo |
|---|---|---|
| Tier 1 | TypeScript, Python, C#, Go, Rust, Ruby | Opción por defecto: soporte más completo del protocolo |
| Tier 2 | Java | Equipos Java o Spring que quieren quedarse en su stack |
| Tier 3 | Swift, PHP, Kotlin | Cuando el lenguaje lo impone; revisa qué parte del protocolo cubren |
TypeScript
El ecosistema con más ejemplos y el que recomienda la skill mcp-builder de Anthropic. Encaja si tu equipo ya trabaja con Node.js.
Python
El camino más corto: los tipos y el docstring de una función generan la definición de la herramienta. Ideal si tu lógica ya está en Python.
PHP con Laravel
Si tu aplicación es Laravel, el paquete laravel/mcp te deja exponer tools, resources y prompts reutilizando modelos, políticas y autenticación.
04 Crear un servidor MCP en Python
El quickstart oficial usa uv como gestor de proyectos. Vamos a crear un servidor con una herramienta que consulta facturas; la lógica real (tu base de datos o tu API) la pones dentro de la función.
-
1
Crea el proyecto
Ejecuta uv init facturas, entra en la carpeta y añade la dependencia con uv add "mcp[cli]". El extra cli instala el comando mcp, que usarás para probar y ejecutar el servidor.
-
2
Instancia el servidor
En server.py importa la clase con from mcp.server import MCPServer y crea la instancia: mcp = MCPServer("facturas").
-
3
Declara la herramienta
Decora una función con @mcp.tool(). El nombre de la función será el de la herramienta, los tipos de los parámetros forman el esquema de entrada y el docstring se convierte en la descripción.
-
4
Arranca por stdio
Al final del archivo añade mcp.run(transport="stdio") dentro del bloque if __name__ == "__main__". Así lo podrá lanzar un cliente local como Claude Desktop.
-
5
Pruébalo con el Inspector
Ejecuta uv run mcp dev server.py: abre el servidor en MCP Inspector para que llames a la herramienta antes de conectarlo a ningún cliente.
-
6
Sírvelo por HTTP cuando toque
Con uv run mcp run server.py --transport streamable-http el mismo servidor responde en http://localhost:8000/mcp, la base de un servidor remoto.
@mcp.tool()def facturas_pendientes(cliente: str) -> str: """Devuelve las facturas sin cobrar de un cliente por su nombre o CIF.""" return buscar_pendientes(cliente)
Fíjate en que el docstring dice qué hace, qué acepta y qué devuelve. Esa frase es la que leerá el modelo para decidir si la llama.
05 Crear un servidor MCP en TypeScript
El quickstart de TypeScript pide Node.js 20 o superior y usa zod para definir el esquema de entrada. La estructura es la misma que en Python: instancia, herramientas y transporte.
-
1
Instala las dependencias
Dentro de un proyecto npm, ejecuta npm install @modelcontextprotocol/server zod, y como dependencias de desarrollo typescript y @types/node. Marca el package.json con "type": "module".
-
2
Crea una función que construya el servidor
Dentro de createServer() instancia new McpServer({ name: "facturas", version: "1.0.0" }) y devuélvelo. Cada llamada debe devolver una instancia nueva.
-
3
Registra cada herramienta
Usa server.registerTool con el nombre, un objeto con description e inputSchema (por ejemplo z.object({ cliente: z.string().describe("Nombre o CIF") })) y la función que devuelve el resultado en content.
-
4
Sirve por stdio
Importa serveStdio desde @modelcontextprotocol/server/stdio y llama a serveStdio(createServer). Negocia la versión con cada cliente, así que atiende tanto a clientes 2026-07-28 como a los que siguen en la versión de 2025.
-
5
Compila y comprueba
Compila con npm run build y lista las herramientas con el Inspector en modo CLI antes de configurarlo en un cliente.
06 Servidor MCP con Laravel (laravel/mcp)
Si tu producto ya es una aplicación Laravel, lo más práctico es exponer el servidor MCP desde la propia aplicación con el paquete oficial laravel/mcp. Las herramientas reutilizan tus modelos, tus servicios y tus políticas de autorización, y el servidor se publica como una ruta más. Es el enfoque que usamos en los proyectos de desarrollo de aplicaciones web a medida con Laravel.
-
1
Instala el paquete
composer require laravel/mcp y después php artisan vendor:publish --tag=ai-routes, que crea el archivo routes/ai.php donde se registran los servidores.
-
2
Genera el servidor
php artisan make:mcp-server FacturasServer crea la clase del servidor, donde indicas su nombre, instrucciones y la lista de herramientas, recursos y prompts.
-
3
Genera cada herramienta
php artisan make:mcp-tool FacturasPendientesTool. La clase tiene una descripción, un método schema() que define los parámetros y un método handle() que devuelve la respuesta, por ejemplo con Response::text().
-
4
Registra la ruta
En routes/ai.php usa Mcp::web('/mcp/facturas', FacturasServer::class) para un servidor HTTP, o Mcp::local('facturas', FacturasServer::class) para uno que se lanza desde la línea de comandos.
-
5
Pruébalo
php artisan mcp:inspector mcp/facturas abre el MCP Inspector apuntando a tu servidor, con autenticación incluida si la tienes configurada.
07 Probar el servidor con MCP Inspector
MCP Inspector es la herramienta de referencia para probar y depurar servidores. Se ejecuta con npx @modelcontextprotocol/inspector, sin instalar nada, y necesita Node.js 22.19.0 o superior. Úsalo siempre antes de conectar el servidor a Claude o ChatGPT: ahí ves el JSON exacto que va y viene, sin un modelo de por medio que maquille los errores.
| Modo | Comando | Para qué |
|---|---|---|
| Web | npx @modelcontextprotocol/inspector node build/index.js | Interfaz gráfica en el navegador para explorar herramientas, recursos y prompts |
| CLI | npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list | Salida legible por máquinas: scripts, CI y agentes de programación |
| TUI | npx @modelcontextprotocol/inspector --tui node build/index.js | Interfaz en la terminal cuando no tienes navegador |
| Remoto | npx @modelcontextprotocol/inspector --server-url https://tu-dominio/mcp --transport http | Probar un servidor desplegado, incluido el flujo OAuth |
- ✓La lista de herramientas aparece completa y en el mismo orden en cada petición.
- ✓Cada herramienta tiene una descripción que se entiende sin leer el código.
- ✓Los parámetros obligatorios están marcados y los inválidos devuelven un error que explica cómo corregirlos.
- ✓Los errores de negocio (cliente inexistente, fecha pasada) vuelven como resultado con isError, no como fallo del servidor.
- ✓Las respuestas son cortas y filtradas: nada de devolver mil registros cuando bastan veinte.
- ✓Sin token o con un token caducado, el servidor remoto responde 401.
08 Conectar tu servidor MCP a Claude y ChatGPT
Cada cliente tiene su forma de añadir servidores, y los nombres de los menús cambian con frecuencia. Estos son los caminos actuales; en las guías de MCP en Claude y MCP en ChatGPT los vemos con más detalle.
| Cliente | Servidor local | Servidor remoto |
|---|---|---|
| Claude Desktop | Entrada en mcpServers del archivo claude_desktop_config.json, con el comando que lanza el servidor | Como conector personalizado, igual que en la web |
| Claude (web y apps) | No aplica | Customize > Connectors > Add custom connector, con la URL HTTPS del servidor. El plan Free admite un conector personalizado |
| Claude Code | claude mcp add mi-servidor -- comando-que-lo-lanza | claude mcp add --transport http mi-servidor https://tu-dominio/mcp y después /mcp para iniciar sesión |
| ChatGPT | No aplica: solo se conecta a servidores remotos | Plugins > Add custom MCP server, con la URL pública HTTPS terminada en /mcp y la autenticación |
-
1
Publica una URL accesible
Los clientes web se conectan desde su propia infraestructura, no desde tu ordenador. Para probar un servidor que corre en local necesitas un túnel HTTPS o un servidor de pruebas.
-
2
Añade el conector
Introduce la URL completa del endpoint MCP y elige el tipo de autenticación. Si el servidor usa OAuth, el cliente abrirá la pantalla de inicio de sesión.
-
3
Pruébalo con las frases reales
Abre una conversación nueva, activa el conector y lanza las frases de usuario que escribiste al principio. Comprueba qué herramienta elige el modelo y con qué argumentos.
-
4
Refresca tras cada cambio
Si cambias nombres, descripciones o esquemas, vuelve a cargar las herramientas en el cliente (en ChatGPT, con Refresh) y repite las pruebas en una conversación nueva.
09 OAuth y permisos para un servidor MCP remoto
En cuanto el servidor es remoto y accede a datos de tus usuarios, la autenticación deja de ser opcional en la práctica. La especificación de MCP define cómo hacerlo sobre HTTP con OAuth 2.1: tu servidor MCP actúa como servidor de recursos y un servidor de autorización (el tuyo o un proveedor de identidad) emite los tokens. Es justo el escenario de una plataforma SaaS a medida, donde cada cliente debe ver solo sus datos. Para servidores locales por stdio la recomendación es otra: leer las credenciales del entorno.
-
1
Responde 401 con pistas
Una petición sin token recibe HTTP 401 con la cabecera WWW-Authenticate, que indica dónde están los metadatos del recurso protegido y, si quieres, los scopes necesarios.
-
2
Publica los metadatos del recurso protegido
Es obligatorio implementar OAuth 2.0 Protected Resource Metadata (RFC 9728): un documento que dice al cliente qué servidor de autorización usar.
-
3
Deja que el cliente se registre
La especificación prefiere los Client ID Metadata Documents; el registro dinámico de clientes sigue admitido por compatibilidad, pero está marcado como obsoleto.
-
4
El usuario inicia sesión y autoriza
El cliente abre el navegador con PKCE y el parámetro resource que identifica tu servidor. El usuario entra con su cuenta y acepta los permisos.
-
5
Valida cada token
El token llega en la cabecera Authorization de cada petición. Comprueba que es válido y que se emitió para tu servidor; nunca reenvíes ese token a otras APIs.
- ✓Scopes mínimos al conectar y más permisos solo cuando una operación los pide, con un 403 insufficient_scope.
- ✓La lista de herramientas puede variar según los permisos del token: quien no puede facturar no ve la herramienta de facturar.
- ✓Cada herramienta comprueba en tu backend que el usuario puede tocar ese registro concreto, aunque el modelo pida otra cosa.
- ✓Confirmación explícita antes de crear, modificar, enviar o borrar, con un resumen de lo que se va a hacer.
- ✓Registro de actividad: quién, qué herramienta, con qué argumentos y con qué resultado.
- ✓Límite de peticiones por usuario y validación de todas las entradas.
10 Desplegar y mantener el servidor, errores comunes y cuándo pedir ayuda
Un servidor remoto es una aplicación web más: necesita HTTPS, monitorización, copias y actualizaciones. Con Streamable HTTP cada mensaje es una petición POST a un único endpoint, y la respuesta llega como JSON o como un flujo SSE ligado a esa petición. El transporte SSE antiguo está obsoleto: si un tutorial lo usa, está desfasado.
- ✓Endpoint con HTTPS y un dominio estable; cambiar la URL obliga a reconectar a todos los usuarios.
- ✓Logs del servidor y del registro de actividad separados, sin tokens ni datos personales innecesarios.
- ✓Versionado de herramientas: si cambias un parámetro, mantén compatibilidad o avisa antes.
- ✓Pruebas automáticas con el Inspector en modo CLI dentro de tu integración continua.
- ✓Revisión periódica del SDK: la especificación evoluciona y los SDK adoptan cada revisión a su ritmo.
Demasiadas herramientas
Cada herramienta ocupa contexto y aumenta la probabilidad de que el modelo elija mal. Agrupa por tareas y quita lo que nadie usa.
Descripciones vagas
«Gestiona clientes» no ayuda. Di qué hace, cuándo usarla, qué parámetros espera y qué devuelve, con un ejemplo si hace falta.
Exponer la API tal cual
Una API está pensada para programadores; un servidor MCP, para un modelo que razona sobre tareas y necesita herramientas con sentido de negocio.
Escribir sin confirmación
Enviar un email, emitir una factura o borrar un registro sin que la persona lo apruebe es el error que más caro sale.
Respuestas enormes
Devolver tablas completas satura el contexto. Pagina, filtra y devuelve solo los campos que responden a la pregunta.
Errores mudos
Un «error 500» no le dice nada al modelo. Devuelve mensajes que expliquen qué falló y cómo corregir la llamada.
Sobre el tercer punto, si dudas entre ampliar tu API o crear un servidor, lee las diferencias entre MCP y una API antes de decidir.
Preguntas frecuentes
Saber programar en alguno de los lenguajes con SDK oficial (TypeScript, Python, C#, Go, Rust, Ruby, Java, Swift, PHP o Kotlin), tener claras las tareas que quieres resolver y un cliente para probarlo, como Claude Desktop o MCP Inspector.
No traduzcas cada endpoint en una herramienta. Parte de las tareas que hará el usuario, crea pocas herramientas que combinen las llamadas necesarias a tu API y devuelve solo los datos útiles, con descripciones claras y errores que expliquen cómo corregir la llamada.
Es la herramienta oficial para probar y depurar servidores MCP. Se lanza con npx @modelcontextprotocol/inspector seguido del comando que arranca tu servidor, o con --server-url para uno remoto, y tiene modo web, modo CLI y modo terminal.
Ambos son SDK de nivel 1, con el soporte más completo del protocolo. Elige el lenguaje en el que ya está tu lógica de negocio: Python es muy directo gracias a los tipos y docstrings, y TypeScript tiene más ejemplos y es el que recomienda la skill mcp-builder de Anthropic.
Sí. El paquete oficial laravel/mcp permite definir servidores, herramientas, recursos y prompts con comandos artisan, publicarlos como rutas web o locales, protegerlos con Passport o Sanctum y probarlos con php artisan mcp:inspector.
No directamente. ChatGPT solo se conecta a servidores remotos por una URL HTTPS pública, así que para probar uno local necesitas un túnel o desplegarlo en un servidor de pruebas.
Si es local por stdio, no: las credenciales se leen del entorno. Si es remoto y accede a datos de distintos usuarios, sí conviene implementar OAuth 2.1 tal como define la especificación de autorización de MCP, porque es el método que más clientes admiten.
Fuentes consultadas
Sobre el autor
Development Manager en appyweb
Dirige el equipo de desarrollo de appyweb: aplicaciones web y móviles, SaaS, integraciones y arquitectura de software.
Ver perfil y artículos → Ver perfil en LinkedIn ↗
