Ir al contenido
Mastering Claude

Inicio / Extender: habilidades, MCP, subagentes, hooks, plugins

Extender: habilidades, MCP, subagentes, hooks, plugins9 minApplication

Construir tu propio servidor MCP

Un servidor MCP casero se lanza como proceso hijo mediante transporte stdio, declara en inputSchema un esquema JSON que el propio servidor debe validar, y una descripción precisa decide cuándo Claude lo llama.

Un servidor MCP construido de forma casera no es más que un programa ordinario que lee y escribe en su entrada y salida estándar siguiendo el protocolo MCP. Claude Code lo lanza él mismo como proceso hijo, mediante el transporte stdio, sin que ese programa escuche jamás un puerto de red. El mismo mecanismo sirve para una herramienta interna, conectada a una base de datos privada, que ningún servidor público podría exponer sin riesgo.

Declararlo ante Claude Code

El comando de registro separa claramente lo que pertenece a Claude Code de lo que pertenece al servidor: claude mcp add --env CLE=valeur --transport stdio nom-du-serveur -- commande arguments. Todo lo que sigue al doble guion se transmite tal cual al servidor, sin interpretación; todo lo que lo precede, --transport o --env, configura la conexión del lado de Claude Code.

claude mcp add --env DEPOT=./donnees --transport stdio compteur -- node ./serveurs/compteur.js

El proceso compteur.js se inicia entonces en cada sesión que lo necesita, recibe la variable DEPOT en su entorno, y se comunica con Claude Code mediante mensajes escritos en su salida estándar.

El esquema decide qué entra, la descripción decide si se le llama

Cada herramienta declara un esquema JSON que delimita sus argumentos válidos. Una herramienta que cuenta las palabras de un texto puede exigir una cadena obligatoria y rechazar cualquier otro tipo:

{
  "name": "compter_mots",
  "description": "Compte le nombre de mots dans un texte fourni en argument.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "texte": { "type": "string" }
    },
    "required": ["texte"]
  }
}

Este esquema declara lo que espera la herramienta, un argumento ausente o del tipo equivocado no es conforme a él, pero la validación sigue siendo responsabilidad del servidor: la especificación MCP obliga al servidor a validar cada entrada de herramienta, el esquema no es una garantía aplicada del lado del cliente antes de la llamada. El esquema tampoco decide si Claude elige esa herramienta en vez de otra: es el campo description el que cumple ese papel, exactamente igual que para una skill. Una descripción que promete más de lo que la herramienta hace realmente, por ejemplo contar las palabras de cualquier documento sin precisar que solo lee un argumento de texto ya proporcionado, se vuelve en tu contra en cuanto Claude confía en ella para un caso que no cubre.

La lección anterior muestra cómo verificar que un servidor así declarado aparece efectivamente conectado antes de confiar en él.

Figure 1

De la solicitud a la llamada de herramienta MCP

01
Lectura de la descripción
Claude compara la tarea en curso con la descripción de cada herramienta disponible y retiene la que corresponde.
02
Construcción de los argumentos
Claude prepara los argumentos que va a pasar, a partir del contexto de la conversación.
03
Envío al servidor
Los argumentos construidos se envían tal cual al servidor, sin validación del lado del cliente contra el esquema declarado.
04
Validación y luego ejecución
El servidor, lanzado por Claude Code como proceso hijo mediante stdio, valida él mismo los argumentos recibidos contra su esquema antes de ejecutar el código y devolver un resultado en su salida estándar.
La secuencia muestra las cuatro etapas que separan una solicitud formulada en la conversación de la ejecución real del código del servidor.
Calíbralo tú mismo

Un ingeniero registra un servidor MCP casero con claude mcp add --transport stdio compteur -- node ./serveurs/compteur.js, cuya única herramienta declarada exige un argumento de texto de tipo cadena. Después le pide a Claude que cuente las palabras de un número entero que escribe directamente en la conversación.

Escribe en una frase lo que esta situación establece, y en una frase lo que no establece.

Lo que hay que recordar
  • Un servidor MCP casero es un programa ordinario lanzado como proceso hijo por Claude Code mediante el transporte stdio, sin abrir nunca un puerto de red.
  • El doble guion en el comando claude mcp add separa las opciones de Claude Code, --transport y --env, del comando y los argumentos transmitidos tal cual al servidor.
  • Un esquema JSON, en el campo inputSchema, declara los argumentos válidos de una herramienta, pero es al código del servidor, nunca al cliente, a quien la especificación obliga a validar cada llamada recibida.
  • La descripción de una herramienta, no su esquema, decide si Claude la elige para una tarea determinada, exactamente igual que para una skill.
Hazlo ahora

Escribe, en un archivo de texto de tu equipo, el esquema JSON de una herramienta imaginaria con un único argumento obligatorio, inspirándote en el ejemplo de esta lección, sin registrarlo ante Claude Code.

Verificar en la fuente

Cada afirmación datable de esta lección remite aquí al texto público que la respalda. Una fuente que no se abre no prueba nada.