Cómo crear un servidor MCP, y cuándo no hacerlo

Para crear un servidor MCP se elige un transporte, se registran unas pocas herramientas con nombre, descripción y esquema de entrada, y se conecta a un cliente como Claude Code. Use stdio para una herramienta local y Streamable HTTP para un servidor remoto que usan muchas personas. El código es la parte pequeña. Qué herramientas expone, y con qué permisos, decide si puede dejar que un agente lo use.

Un servidor MCP es la forma en que su sistema habla con agentes de IA. Usamos a diario servidores MCP de otros y hemos construido uno propio: un prototipo para una empresa de transporte y logística cuyo sistema construimos y operamos. Se quedó en prototipo. A continuación: cómo crear uno, qué haríamos de otra manera y cuándo no lo necesita en absoluto.

¿Qué es un servidor MCP?

El Model Context Protocol es un estándar abierto para conectar clientes de IA con herramientas y datos. Un servidor ofrece herramientas (acciones), recursos (datos) y prompts. Un cliente, como Claude Code, Claude Desktop o un agente que usted construya, lista las herramientas y las llama cuando la tarea lo requiere. Los mensajes son JSON-RPC.

El agente nunca ve su base de datos. Ve una lista como esta:

• find_order: busca un pedido por su número. Solo lectura.
• draft_reply: redacta un borrador de respuesta para que lo apruebe una persona.

El nombre y la descripción son su interfaz. El modelo elige una herramienta leyéndolos, así que una descripción vaga hace que una herramienta se llame en el momento equivocado.

¿stdio o Streamable HTTP: local o remoto?

La especificación de MCP define dos transportes estándar. La elección decide dónde se ejecuta el servidor y cómo se autentica.

La autorización depende del transporte. La especificación de autorización dice que las implementaciones con stdio «SHOULD NOT follow this specification, and instead retrieve credentials from the environment», es decir, no deben usar ese procedimiento de autorización y deben tomar las credenciales del entorno. Un servidor remoto actúa como servidor de recursos OAuth 2.1 y debe comprobar que cada token que recibe se emitió para él.

¿Cómo se crea un servidor MCP paso a paso?

Un servidor mínimo con el SDK oficial de TypeScript v2 (paquete @modelcontextprotocol/server, a 10/2026):

import { McpServer } from '@modelcontextprotocol/server'
import { serveStdio } from '@modelcontextprotocol/server/stdio'
import * as z from 'zod/v4'
import { getOrder } from './api.js'

function createServer() {
  const server = new McpServer({ name: 'orders', version: '0.1.0' })

  server.registerTool(
    'find_order',
    {
      title: 'Find an order',
      description: 'Look up one order by its order number. Read-only.',
      inputSchema: z.object({ orderNumber: z.string() }),
    },
    async ({ orderNumber }) => {
      const order = await getOrder(orderNumber) // your API, with the caller's rights
      return { content: [{ type: 'text', text: JSON.stringify(order) }] }
    },
  )

  return server
}

void serveStdio(createServer)

Conéctelo a Claude Code:

claude mcp add orders -- node dist/server.js

Con stdio casi todo el mundo cae en una trampa. La especificación dice que el servidor «MUST NOT write anything to its stdout that is not a valid MCP message»: en stdout no puede ir nada que no sea un mensaje MCP. Un console.log olvidado rompe la conexión. Registre los logs en stderr.

Después pruebe con el cliente real y la tarea real. Cuando un agente elige la herramienta equivocada, revise la descripción antes de tocar el código.

¿Qué aprendimos de nuestro propio prototipo MCP?

Nuestro prototipo era un servidor local con stdio sobre el SDK oficial, a partir de una plantilla inicial de código abierto. Tenía una sola herramienta de lectura y llamaba a la API interna existente del sistema con un inicio de sesión provisional. Suficiente para ver a un agente responder preguntas con datos reales. No suficiente para que alguien lo usara a diario.

Qué haríamos de otra manera:

• Primero la API. Un servidor MCP es una capa fina sobre una API. El nuestro se apoyaba en endpoints hechos para las pantallas de la propia aplicación. Primero debería existir una API limpia con sus propias reglas de acceso. Cómo lo vemos lo explicamos en API de Pohoda: conectar su sistema y quién lo mantiene.
• Un inicio de sesión real desde el primer día. Un inicio de sesión provisional sirve para una tarde. Es lo primero que hay que sustituir, porque decide qué puede ver el agente.
• La tarea antes que el servidor. Construimos el servidor antes de saber qué tarea haría un agente con él cada día. El orden correcto es la tarea, luego las herramientas que necesita, luego el servidor.

Con franqueza: todavía no hemos tenido un servidor MCP remoto en producción. Todo lo anterior sobre Streamable HTTP y OAuth viene de la especificación, no de nuestros propios incidentes.

¿Qué herramientas debería recibir un agente?

Empiece solo con lectura y añada permisos de uno en uno. Nuestro punto de partida:

Aquí vale la misma regla que usamos con nuestros propios agentes. Hacer merge, enviar y desplegar se queda en manos de una persona, y se impone por debajo del agente, no con una frase en su prompt. Cómo funciona eso en Claude Code lo explicamos en Hooks de Claude Code que no hacen nada en silencio.

¿Cuándo no debería crear un servidor MCP?

Un servidor MCP sirve para el caso en que un agente de IA decide qué acción tomar a continuación. Muchas tareas nunca lo necesitan.

No lo haga cuando:

• Su propio código es el único que llama. Llame a su API directamente.
• La tarea es una secuencia fija. Ahí una automatización normal gana a un agente.
• Aún no hay una API limpia. Constrúyala primero.
• Nadie es responsable del modelo de permisos. ¿En nombre de quién puede actuar el agente y qué puede hacer? Sin respuesta, no exponga escrituras.

Antes de poner en marcha un servidor MCP

¿Quiere que su sistema trabaje con agentes de IA?

Construimos agentes de IA y lo que necesitan por debajo, desde una API limpia hasta el servidor MCP encima, como parte de agentes de IA para empresas. Para un equipo que quiere agentes dentro de su propio proceso de desarrollo, vea AI-native SDLC para equipos de desarrollo. Desde 2023 hemos entregado más de 15 proyectos en producción.

Le respondemos en dos días laborables con unas preguntas sobre su trabajo. Después acordamos qué hacemos primero.

Si prefiere hablar primero, reserve una llamada inicial de 15 minutos.

¿Qué tarea de su sistema le daría primero a un agente?

Preguntas frecuentes

¿Qué es un servidor MCP?

Un programa que ofrece herramientas, datos y prompts a un cliente de IA mediante el Model Context Protocol. El agente ve cada herramienta por su nombre, descripción y esquema de entrada y decide cuándo llamarla. Su sistema queda detrás de su propio código.

¿Uso stdio o Streamable HTTP?

stdio cuando el servidor se ejecuta en la misma máquina que el cliente, por ejemplo una herramienta local para Claude Code. Streamable HTTP cuando se ejecuta en remoto para varios usuarios. Un servidor remoto necesita una autorización de verdad.

¿Cómo añado un servidor MCP a Claude Code?

Para un servidor local: claude mcp add <nombre> -- <comando>. Para uno remoto: claude mcp add --transport http <nombre> <url>. Los servidores que debe tener todo el equipo van en .mcp.json, en el repositorio.

¿Cómo se protege un servidor MCP?

En local, lea las credenciales del entorno. En remoto, siga la especificación de autorización de MCP, basada en OAuth 2.1, y compruebe que cada token se emitió para su servidor. Ofrezca las menos herramientas posibles, primero solo de lectura.

¿Necesito un servidor MCP para mi producto?

Solo si los agentes de IA deben trabajar con su sistema y elegir qué hacer. Si su propio código es el único que llama, o los pasos son siempre los mismos, una llamada directa a la API o una tarea programada es más sencilla y más fácil de probar.