Tutorial de servidor MCP: instalación, ejemplos y primera herramienta para principiantes

Tu asistente de IA puede escribir un soneto sobre hojas de cálculo, pero si le preguntas cuánto pesa un archivo de tu equipo portátil, se encoge de hombros. El Model Context Protocol cierra esa brecha. Un servidor MCP es un pequeño programa que da a un asistente capacidades reales: leer una carpeta, consultar una base de datos, llamar a una API o incluso generar una imagen. Este tutorial construye uno desde una carpeta vacía, y termina con una primera herramienta funcionando en unos veinte minutos, sin necesidad de experiencia previa con protocolos.

Instalarás el SDK, escribirás una herramienta, la probarás en el Inspector, la conectarás a un cliente real y, después, verás cómo el mismo patrón impulsa la generación de imágenes y video en PicassoIA. Todo funciona con Python estándar, así que si sabes leer una función, podrás seguir los pasos.

Qué hace un servidor MCP

La analogía del USB-C

Antes del USB-C, cada aparato necesitaba su propio cable. MCP hace por la IA lo que ese único puerto hizo por el hardware. Sin él, cada asistente necesitaba código a medida para cada servicio, lo que equivalía a N asistentes por M servicios de pegamento. Con él, escribes un solo servidor y cualquier cliente compatible con MCP puede usarlo.

Anthropic presentó el protocolo a finales de 2024, y desde entonces muchas aplicaciones de chat, editores de código y frameworks de agentes lo han adoptado. Esa adopción es la razón real para dedicarle tiempo: una herramienta que construyes hoy no está atada a un solo producto, y las habilidades que adquieres sirven para cada cliente que hable el protocolo.

Host, cliente y servidor

En cada conversación MCP aparecen tres roles, y los principiantes suelen confundirlos.

Los mensajes viajan como JSON-RPC 2.0. Un servidor local habla por stdio: el host lanza tu script como proceso hijo e intercambia mensajes a través de sus flujos de entrada y salida. Un servidor remoto habla por Streamable HTTP, que es como funcionan los conectores alojados.

Esto es lo que ocurre cuando haces una pregunta:

1. El host inicia tu servidor, y su cliente pregunta: "¿Qué puedes hacer?"
2. El servidor responde con una lista de herramientas y el esquema de cada una.
3. Haces una pregunta. El modelo decide que una herramienta encaja y emite una llamada con argumentos.
4. El host muestra una solicitud de permiso y, después, reenvía la llamada a tu servidor.
5. Tu función se ejecuta, el resultado vuelve y el modelo escribe la respuesta final.

Herramientas, recursos y prompts

Un servidor puede ofrecer tres tipos de elementos, y cada uno tiene un responsable distinto.

💡 Empieza por las herramientas. Son la primitiva con mayor soporte, y una sola herramienta funcionando te enseña gran parte de lo que el protocolo exige.

Prepara tu entorno

Qué necesitas

Reúne cuatro cosas antes de escribir código:

• Python 3.10 o superior. Compruébalo con python --version.
• Node.js 18 o superior, solo para el depurador Inspector, que se ejecuta con npx.
• Una terminal y cualquier editor de código, incluso uno sencillo.
• Un cliente MCP, como Claude Desktop, Claude Code o un editor compatible.

Funciona en Windows, macOS y Linux. Solo cambia el comando que activa el entorno virtual, y el código de abajo es idéntico en todos los sistemas.

¿Python o TypeScript?

Existen SDK oficiales para varios lenguajes. Dos son la opción más segura para un primer servidor:

Este tutorial usa Python. Los conceptos, desde las herramientas hasta los transportes, se trasladan sin cambios a cualquier otro SDK.

Escribe tu primera herramienta

Crea el proyecto

Crea una carpeta, añade un entorno aislado e instala el SDK:

mkdir word-counter
cd word-counter
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install "mcp[cli]"

Copiar prompt

El extra [cli] instala el comando mcp, que incluye un ejecutor de desarrollo para pruebas rápidas.

Tu herramienta en 15 líneas

Crea server.py con este contenido:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("word-counter")

@mcp.tool()
def count_words(text: str) -> dict:
    """Count the words, characters and lines in a piece of text."""
    return {
        "words": len(text.split()),
        "characters": len(text),
        "lines": len(text.splitlines()),
    }

if __name__ == "__main__":
    mcp.run(transport="stdio")

Copiar prompt

Tres detalles hacen todo el trabajo:

1. La docstring es lo que el modelo lee para decidir cuándo llamar a la herramienta. Escríbela como si fuera una descripción de puesto de una línea.
2. Las anotaciones de tipo (text: str) se convierten en el esquema JSON que indica al cliente qué argumentos existen y qué tipo tiene cada uno.
3. El valor de retorno se serializa y se envía al modelo como resultado de la herramienta.

Cuando un cliente se conecta, pide a tu servidor la lista de herramientas. FastMCP responde con el nombre count_words, tu docstring como descripción y un esquema de entrada generado a partir de la firma: un objeto con una propiedad obligatoria de tipo cadena llamada text. Ese pequeño documento JSON es todo lo que el modelo sabe de tu función, por eso los nombres y la redacción importan más que el código ingenioso.

💡 Si una herramienta nunca se llama, la causa casi siempre es una docstring vaga, no un error en tu código.

Pruébala en el Inspector

No conectes todavía una app de chat. Depura en el MCP Inspector, un banco de pruebas que funciona en el navegador:

npx @modelcontextprotocol/inspector python server.py

Copiar prompt

Se abre una página local. Luego:

1. Haz clic en Connect para lanzar tu servidor.
2. Abre la pestaña Tools y pulsa List Tools. count_words debería aparecer.
3. Selecciónala, escribe una frase en el campo text y ejecútala.
4. Comprueba que el resultado JSON muestra los recuentos correctos.

⚠️ Nunca uses print() en un servidor stdio. La salida estándar es el canal de mensajes, y un print suelto lo corrompe. Envía los logs a stderr o usa el módulo logging de Python.

Conéctalo a un cliente real

Cuando el Inspector muestre todo en verde, registra el servidor en un cliente. En Claude Desktop, añade esto al archivo claude_desktop_config.json:

{
  "mcpServers": {
    "word-counter": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Copiar prompt

En Claude Code, un solo comando hace lo mismo:

claude mcp add word-counter -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py

Copiar prompt

Reinicia la aplicación por completo y pregunta: "¿Cuántas palabras tiene este párrafo?" seguido de algo de texto. El cliente pide permiso, ejecuta count_words y responde con las cifras exactas en lugar de una suposición.

Si no aparece nada, revisa estos puntos en orden:

• Solo rutas absolutas. Las rutas relativas fallan porque el host lanza el proceso desde su propia carpeta.
• Apunta al intérprete del venv. Un python suelto suele encontrar otra instalación sin el SDK.
• Cierra la aplicación por completo. Cerrar la ventana suele dejarla ejecutándose en la bandeja.
• Lee los logs. Los clientes escriben registros por servidor que muestran el traceback exacto.

Cuando un script local ya no basta, cambia el transporte con mcp.run(transport="streamable-http"), aloja el servidor detrás de HTTPS y añade autenticación. El código de la herramienta sigue siendo exactamente el mismo, que es la recompensa silenciosa de construir sobre un protocolo.

Tres ejemplos que vale la pena copiar

Un recurso de solo lectura

Los recursos exponen datos mediante una URI. Este sirve un archivo de notas:

from pathlib import Path

@mcp.resource("notes://today")
def todays_notes() -> str:
    """Return the contents of today's notes file."""
    return Path("notes/today.md").read_text(encoding="utf-8")

Copiar prompt

La aplicación puede adjuntarlo como contexto sin que el modelo llame a nada. Los recursos también pueden usar plantillas de URI como notes://{date}, así que una sola función sirve a toda una familia de archivos.

Una plantilla de prompt

Un prompt es un punto de partida reutilizable que el usuario elige de un menú. A diferencia de una herramienta, el modelo nunca decide ejecutarlo: el usuario lo elige y el resultado se convierte en el mensaje inicial de la conversación.

@mcp.prompt()
def review_code(code: str) -> str:
    """Ask for a short, friendly code review."""
    return f"Review this code and list the three most important fixes:\n\n{code}"

Copiar prompt

Una herramienta que llama a una API

La mayoría de los servidores reales envuelven un servicio web. Este comprueba si un sitio está en línea:

import httpx

@mcp.tool()
async def check_site(url: str) -> str:
    """Return the HTTP status code of a website."""
    async with httpx.AsyncClient(timeout=10) as client:
        response = await client.get(url, follow_redirects=True)
    return f"{url} answered with status {response.status_code}"

Copiar prompt

httpx viene ya incluido con el SDK, y declarar la función como async permite que el servidor siga respondiendo mientras espera a la red. Las llamadas de red fallan, así que captura la excepción y devuelve un mensaje corto y legible. Un modelo que ve "el sitio agotó el tiempo de espera tras 10 segundos" puede adaptarse y probar otra cosa, mientras que un traceback en bruto solo lo confunde.

Errores que desperdician tu tarde

Los nombres ayudan tanto como la tabla anterior. Elige verbos que digan lo que ocurre, como count_words o check_site, mantén cada herramienta con una sola tarea y limita los argumentos a los pocos que el modelo realmente necesita. Una herramienta llamada process con seis campos opcionales es una invitación a adivinar mal.

Protege el acceso

Una herramienta es código que el modelo puede ejecutar en tu equipo, así que trátala con cuidado:

• Prefiere las herramientas de solo lectura. Añade herramientas de escritura o borrado solo cuando las necesites de verdad.
• Valida las entradas. Una herramienta de archivos debe rechazar rutas fuera de una carpeta elegida.
• Mantén los secretos fuera del código. Pasa los tokens mediante el campo env de la configuración del cliente, que los mantiene fuera de tu repositorio.
• Lee la solicitud de permiso. No apruebes una llamada a herramienta que no sepas explicar.

Conecta PicassoIA mediante MCP

Qué ofrece el conector

Los servidores no se limitan a scripts locales. PicassoIA expone la generación de imágenes y video a los clientes MCP, así que un asistente puede crear contenido directamente desde un chat. El conector y la API para desarrolladores comparten los mismos cuatro modelos:

Por debajo, la API sigue un patrón familiar: crear una predicción, consultar su estado y, después, obtener el resultado. Las solicitudes usan un token Bearer, los prompts pueden tener hasta 4000 caracteres, y una cuenta ejecuta hasta 5 predicciones a la vez, compartidas entre tokens y conexiones MCP. Gestiona las conexiones desde la página de MCP de tu cuenta de PicassoIA, y revisa tu plan para saber qué incluye el acceso MCP.

Escribe un borrador de herramienta con un LLM

No tienes que escribir cada herramienta a mano. Los modelos de lenguaje convierten una frase sencilla en un primer borrador que puedes probar en el Inspector:

Describe la herramienta en una frase, pide una versión para FastMCP y ejecútala en el Inspector antes de confiar en ella. Los modelos escriben código verosímil, y el Inspector es la forma de encontrar las partes verosímiles pero incorrectas.

Genera imágenes desde un chat

Una vez conectado, el flujo de trabajo es breve:

1. Abre tu chat con MCP activado y confirma que el conector de PicassoIA está activo.
2. Describe la toma con detalles concretos: sujeto, objetivo, luz y ambiente. Una frase como "una taza de cerámica sobre un escritorio de roble, luz suave de ventana desde la izquierda, objetivo de 50 mm" es mucho mejor que "bonita foto de café".
3. Deja que el asistente llame a PicassoIA Image y espera el resultado.
4. Refina con PicassoIA Image Editor Pro en lugar de empezar de cero.
5. Anima el mejor fotograma con PicassoIA Video.

Trata cada prompt como una lista de verificación breve: sujeto y acción, escenario, dirección de la luz, objetivo y textura de superficie. Mantén una sola idea por imagen y genera en lotes pequeños para quedarte por debajo del límite de cinco a la vez mientras los primeros resultados todavía se renderizan.

💡 La generación es asíncrona. Si un cliente informa "pendiente", significa que está consultando el estado, no que haya fallado.

Pruébalo hoy en Picasso IA

Ya tienes las piezas: un servidor, una primera herramienta, una prueba en el Inspector y una conexión con un cliente. Añade una segunda herramienta esta semana, convierte uno de tus propios scripts en un servidor y observa lo rápido que tu asistente se vuelve útil.

Luego pon a trabajar el lado creativo. Ve a Picasso IA, elige un modelo como PicassoIA Image y genera tu primera imagen a partir de una sola frase. Experimenta con la iluminación, los objetivos y los ambientes, envía el mejor resultado a Seedance 2.5 Lite para darle vida y comprueba hasta dónde llega un buen prompt.