Tutorial de introducción a MCP

MCP, cuyo nombre completo en inglés es Model Context Protocol (Protocolo de Contexto del Modelo), es un protocolo estándar abierto que se utiliza para estandarizar la forma en que las aplicaciones de IA se conectan con herramientas externas y fuentes de datos.

MCP es como USB-C: permite que diferentes dispositivos se conecten entre sí a través de la misma interfaz.

Antes de la aparición de MCP, cada vez que se integraba una nueva herramienta (como GitHub, Slack o una base de datos), cada aplicación de IA debía escribir un conjunto de código de integración por separado, lo que daba lugar alproblema de integración N × M(N aplicaciones de IA × M herramientas = N×M conjuntos de código).

Con MCP, el proveedor de la herramienta solo necesita crear un MCP Server siguiendo el estándar, y cualquier aplicación de IA compatible con MCP puede utilizarlo directamente, convirtiéndose en1 Server + compatible con todos los Host。

La siguiente imagen muestra de forma intuitiva la diferencia entre la integración tradicional N×M y la integración estandarizada de MCP:

传统 N×M 集成 vs MCP 标准化集成对比图

MCP fue donado por Anthropic en diciembre de 2025 a la Agentic AI Foundation (AAIF) de la Linux Foundation, convirtiéndose en un estándar abierto compartido por la industria. OpenAI, Block y otros proveedores participan conjuntamente en su gobernanza.

Cronología de desarrollo

FechaHito
Antes de 2023OpenAI lanzó function calling y el marco de plugins de ChatGPT, pero ambos eran formatos privados del proveedor, vinculados a una única plataforma.
Noviembre de 2024Anthropic publicó MCP, que es independiente del modelo y neutral respecto al proveedor; cualquier modelo puede usar el mismo Server.
Marzo de 2025OpenAI anunció oficialmente su soporte para MCP
Mediados de 2025Se añadieron capacidades como transporte Streamable HTTP, autorización OAuth 2.1 y Elicitation (solicitud de información), llevando a MCP hacia servicios remotos de nivel de producción.
Diciembre de 2025La gobernanza del protocolo se transfirió a AAIF (Linux Foundation), entrando en una etapa de cogobernanza entre múltiples proveedores.
2026El núcleo evoluciona hacia la ausencia de estado (stateless), añadiendo capacidades ampliadas como Tasks (tareas de larga duración) y MCP Apps (UI interactiva).

Arquitectura principal: Host / Client / Server

MCP se inspira en el enfoque de diseño de LSP (Language Server Protocol, el protocolo que permite a los editores admitir lenguajes de programación de forma unificada) y define tres roles:

RolDescripciónEjemplo
Host (anfitrión) La aplicación de IA que el usuario utiliza directamente; se encarga de coordinar múltiples Client y gestionar la conversación. Claude Code、Claude Desktop、Cursor、ChatGPT
Client (cliente) Componente interno del Host que mantiene una conexión uno a uno con un Server; se encarga de traducir las solicitudes de llamada a herramientas del modelo en mensajes de protocolo estándar. El Host crea un Client cada vez que se conecta a un Server.
Server (servidor) Envuelve un protocolo estándar para exponer las capacidades de una herramienta o fuente de datos específica; no conversa directamente con el modelo grande. Server de API de GitHub, Server de base de datos, Server de sistema de archivos

La relación de la arquitectura de tres capas se muestra en la siguiente figura:

MCP 三层架构图:Host / Client / Server

La comunicación subyacente utiliza de forma unificada elJSON-RPC 2.0formato de mensaje, lo que garantiza la estandarización de la interacción entre los diferentes roles.


Explicación detallada del flujo de comunicación de MCP

Tomando como ejemplo "el usuario pide a la IA que consulte el clima", un proceso completo de llamada a herramienta es el siguiente:

MCP 通信流程时序图:用户提问到获取结果的完整链路

El proceso se divide en siete pasos:

  1. Pregunta del usuario: el usuario ingresa "consulta el clima de Beijing" en el Host (como Claude Code).
  2. Juicio del modelo: el modelo grande integrado en el Host analiza el problema, determina que es necesario invocar la herramienta de consulta meteorológica y envía la intención de llamada al Client.
  3. Traducción del protocolo: el Client convierte la solicitud de llamada a herramienta en un mensaje en formato JSON-RPC 2.0 y lo envía al Server correspondiente.
  4. Ejecución del Server: el Server, tras recibir la solicitud, ejecuta la acción real (como llamar a la API del clima o consultar una base de datos).
  5. Devolución del resultado: el Server devuelve el resultado al Client en formato JSON-RPC.
  6. Devolución al modelo: el Client transmite el resultado al Host para que el modelo lo integre en su respuesta.
  7. Respuesta al usuario: el modelo combina los datos devueltos por la herramienta con el lenguaje natural y genera la respuesta final.

Durante todo el proceso, el Server no tiene conocimiento alguno de la existencia del modelo grande: solo procesa mensajes JSON-RPC. Este es el diseño clave con el que MCP logra la independencia del modelo.


Las tres primitivas principales

Un MCP Server puede exponer externamente tres tipos de capacidades, denominadas "primitivas" (Primitive):

PrimitivaDefiniciónEscenario típico
Tools (herramientas) Acciones ejecutables que el modelo puede invocar de forma proactiva y que producen efectos secundarios (como escribir datos o enviar mensajes). Enviar correos electrónicos, crear tickets, ejecutar consultas de base de datos, manipular archivos.
Resources (recursos) Datos de solo lectura que el modelo lee como contexto; no implican ejecución. Contenido de archivos de registro, instantáneas de tablas de base de datos, documentación de API.
Prompts (plantillas de mensajes) Plantillas de mensajes reutilizables escritas de antemano que el usuario o la aplicación pueden invocar directamente. "Resume las cláusulas clave de este contrato", "analiza los problemas de rendimiento de este código".

Además, existen dos mecanismos avanzados:

  • Sampling (muestreo): el Server, a la inversa, puede solicitar al modelo del Host que genere contenido por él, logrando un intercambio de roles.
  • Elicitation (solicitud de información): si el Server descubre a mitad de la ejecución que le falta información, puede preguntar activamente al usuario, por ejemplo, "¿Por qué fecha desea filtrar?"

Al principio, basta con centrarse en Tools y Resources; Prompts, Sampling y Elicitation se pueden conocer más adelante cuando se utilicen.


Métodos de transporte

MCP admite dos métodos de transporte, adecuados para diferentes escenarios:

Método de transporteEscenario de aplicaciónCaracterísticas
stdio (entrada/salida estándar) Herramienta local; el Host inicia el Server como subproceso. El más sencillo, sin necesidad de configuración de red; adecuado para herramientas locales en computadoras personales.
Streamable HTTP Entorno de producción remoto; el Server se implementa como un servicio HTTPS. Admite conexiones concurrentes y escalado horizontal, combinado con OAuth 2.1 para la autenticación.

Para el aprendizaje personal y el desarrollo local, se utilizastdioes suficiente.

Para escenarios empresariales que requieren uso compartido por múltiples personas, se utilizaStreamable HTTP。

Todos los casos de demostración de este tutorial utilizan el método stdio.


Avisos de seguridad

MCP otorga a la IA la capacidad de ejecutar código y acceder a sistemas reales, por lo que las normas de seguridad son especialmente importantes:

  • La descripción de las herramientas no es confiable por sí misma: a menos que provenga de un Server de confianza, la descripción de funciones puede ser manipulada maliciosamente (riesgo de inyección de prompts). El Host debe mantener la cautela respecto a las descripciones de las herramientas.
  • Se debe obtener el consentimiento explícito del usuario: no se pueden ejecutar operaciones sensibles de forma silenciosa; cada llamada a herramienta debe pasar por la confirmación del usuario.
  • Reforzar la protección en entornos de producción: el Server debe implementarse como servidor de recursos OAuth, junto con cifrado TLS, control de acceso y auditoría de registros.
  • Los Server de terceros requieren revisión: confirmar que la fuente sea confiable antes de usarlo y, si es necesario, realizar aislamiento en sandbox.

Demostración práctica: Conectar un MCP Server con Claude Code

A continuación, mediante dos casos completos, se muestra cómo escribir un MCP Server e integrarlo con Claude Code.

El primer caso utiliza Python para escribir un servicio de consulta meteorológica; el segundo caso utiliza Node.js/TypeScript para gestionar una lista de tareas pendientes.

Caso 1: Server de consulta meteorológica en Python

Objetivo: Escribir un MCP Server que proporcione una herramienta de consulta meteorológica y sea invocado a través de Claude Code.

Preparación del entorno

pip install mcp httpx

Es necesario instalar dos paquetes de Python:mcpes el SDK oficial de Python de MCP,httpxse utiliza para realizar solicitudes HTTP y llamar a la API meteorológica.

Escribir el código del servidor

Crear el archivoweather_server.py:

Ejemplo

# Ruta del archivo: weather_server.py
from mcp.server.fastmcp import FastMCP
import httpx

# Crear una instancia de MCP Server llamada "weather"
# FastMCP proporciona una API de alto nivel que simplifica el desarrollo del servidor
mcp = FastMCP("weather")


@mcp.tool()
async def get_weather(city: str) -> str:
    """Consulta el clima actual de una ciudad específica.

    Args:
city: nombre de la ciudad, admite chino o inglés, por ejemplo "Beijing" o "Shanghái"
    """

    # Usa la API meteorológica gratuita wttr.in, no requiere registro de clave API
    # El parámetro format especifica el formato de retorno: %C=condición climática, %t=temperatura
    url = f"https://wttr.in/{city}?format=%C+%t"
    async with httpx.AsyncClient() as client:
        resp = await client.get(url, timeout=10)
        resp.raise_for_status()
        return f"{city} clima actual: {resp.text.strip()}"


@mcp.resource("weather://cities/supported")
def supported_cities() -> str:
    """Devuelve la lista de ciudades admitidas actualmente para consulta (ejemplo de recurso de solo lectura)."""
    return "Beijing, Shanghai, Guangzhou, Shenzhen, Hangzhou, Chengdu, ejemplo"


if __name__ == "__main__":
    # Usa transmisión stdio para que Claude Code lo invoque como subproceso
    mcp.run(transport="stdio")

Explicación del código:

  • @mcp.tool()Registra la función como Tool; el docstring del modelo se proporciona automáticamente como descripción de la herramienta al modelo grande, ayudando al modelo a decidir cuándo debe invocarla.
  • @mcp.resource()Registra la función como Resource, para que el modelo la lea según sea necesario; no implica "ejecución", solo "consulta".
  • mcp.run(transport="stdio")Se comunica con el Host mediante entrada/salida estándar; es la forma más común para herramientas locales.

Depuración local (opcional pero recomendada)

Antes de integrarlo con Claude Code, use primero la herramienta Inspector oficial de MCP para depurar el servidor y confirmar que funciona correctamente:

npx @modelcontextprotocol/inspector python weather_server.py

Después de ejecutarlo, se abrirá automáticamente una interfaz de depuración web, donde se puede ver qué Tool y Resource expone el servidor, y probarlos manualmente.

Se recomienda pasar siempre por el flujo de depuración de Inspector antes de conectarse a un asistente de IA real, para solucionar problemas de código y ahorrar mucho tiempo de depuración.

Configurar MCP Server en Claude Code

Método 1: Hacer que la IA lo agregue directamente

Podemos iniciar Claude directamente:

claude

Ingrese la siguiente información y deje que Claude configure y agregue por usted:

添加 @weather_server.py 这个 MCP 服务

Esta es la forma más sencilla; la configuración y las dependencias se completan automáticamente con solo ingresar la información de solicitud.

Se puede ver que la información de configuración se genera automáticamente en el archivo .mcp.json del directorio actual:

Una vez completada la configuración, pregunte directamente en Claude Code:

Ayúdame a consultar el clima actual en Beijing

Si prefiere hacerlo manualmente, también puede usar la adición mediante comandos y la configuración por archivos.

Método 2: Adición mediante línea de comandos

Tenga en cuenta que las rutas de los comandos y del archivo deben modificarse usted mismo:

claude mcp add weather python /Users/ejemplo/ejemplo-test/weather_server.py

El significado de este comando:

  • claude mcp addSubcomando de gestión MCP de Claude Code.
  • weatherAsigna un nombre a este MCP Server; después se usaclaude mcp listSe puede ver.
  • pythonComando para iniciar el servidor.
  • /Users/.../weather_server.pyRuta absoluta del script del servidor.

Después de agregarlo correctamente, puede usar el siguiente comando para ver los MCP Server conectados:

claude mcp list

Ejemplo de salida:

NAME      STATUS   COMMAND
weather   active   python /Users/ejemplo/ejemplo-test/weather_server.py

Para eliminar algún servidor:

$ claude mcp remove weather

Método 3: Archivo de configuración (adecuado para compartir en equipo)

Cree en la raíz del proyecto.mcp.jsonel archivo:

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/Users/ejemplo/ejemplo-test/weather_server.py"]
    }
  }
}

Después de guardar, reinicie Claude Code (o vuelva a abrir el proyecto) y la configuración tendrá efecto.

La ventaja del método de archivo de configuración es que se puede enviar al repositorio Git; los miembros del equipo obtienen automáticamente la misma configuración de MCP Server después de clonar el proyecto.

Si se configura un MCP Server a nivel de usuario (almacenado en ~/.claude/mcp.json), tendrá efecto en todos los proyectos. El .mcp.json a nivel de proyecto solo tiene efecto en el proyecto actual.

Uso práctico

Una vez completada la configuración, pregunte directamente en Claude Code:

> Ayúdame a consultar el clima actual en Beijing

Claude Code automáticamente:

  1. Identifica la herramienta get_weather del servidor weather que debe invocar.
  2. Muestra un cuadro de diálogo de confirmación de autorización preguntando si permite la invocación.
  3. Después de hacer clic en aceptar, llama al servidor para obtener datos meteorológicos.
  4. Integra el resultado en una respuesta en lenguaje natural.

Este es el ciclo completo desde el modelo hasta los datos del mundo real.

Caso 2: Server de tareas pendientes en Node.js/TypeScript

Si está más familiarizado con el ecosistema JavaScript/TypeScript, aquí tiene un ejemplo de MCP Server en Node.js.

Preparación del entorno

npm install @modelcontextprotocol/sdk zod

Escribir el código del servidor

Crear el archivotodo_server.ts:

Ejemplo

// Ruta del archivo: todo_server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// Crear una instancia de MCP Server, establecer nombre y número de versión
const server = new McpServer({
  name: "todo-list",
  version: "1.0.0"
});

// Usar un arreglo para simular el almacenamiento de tareas pendientes (en proyectos reales se puede reemplazar por una base de datos)
const todos: string[] = [];

// Registrar la primera Tool: agregar tarea pendiente
server.tool(
  "add_todo",                         // Nombre de la Tool
  "Agregar una tarea pendiente",                   // Descripción de la Tool (el modelo usa esto para decidir cuándo llamarla)
  {
    // Esquema de parámetros, definido con Zod, genera automáticamente JSON Schema
    item: z.string().describe("Contenido de la tarea")
  },
  async ({ item }) => {
    todos.push(item);
    return {
      content: [{
        type: "text",
        text:`Se ha agregado:"${item}", actualmente hay ${todos.length}tarea(s) pendiente(s)`
      }]
    };
  }
);

// Registrar la segunda Tool: listar todas las tareas pendientes
server.tool(
  "list_todos",
  "Listar todas las tareas pendientes",
  {},                                 // Sin parámetros
  async () => {
    const text = todos.length
      ? todos.map((t, i) => `${i + 1}. ${t}`).join("\n")
      : "No hay tareas pendientes por ahora";
    return {
      content: [{ type: "text", text }]
    };
  }
);

// Iniciar el servidor usando transmisión stdio
const transport = new StdioServerTransport();
await server.connect(transport);

La forma de integrarlo con Claude Code es exactamente la misma que la versión de Python.

Podemos iniciar Claude directamente:

claude

Ingrese la siguiente información y deje que Claude configure y agregue por usted:

添加 @todo_server.ts 这个 MCP 服务

Luego, en la conversación, diga "ayúdame a agregar una tarea: comprar el tutorial de ejemplo", y Claude Code invocará la herramienta add_todo.


Ecosistema existente: no es necesario escribir todo desde cero

Desde el lanzamiento de MCP, la comunidad ha publicado más de 500 servidores públicos, que cubren la mayoría de los escenarios comunes:

CategoríaEjemplos de MCP Server listos para usar
Alojamiento de códigoGitHub、GitLab、Bitbucket
Mensajería instantáneaSlack、Discord
Almacenamiento en la nubeGoogle Drive、OneDrive
Base de datosPostgreSQL、MySQL、SQLite、MongoDB
Automatización webPuppeteer、Playwright
Gestión del conocimientoNotion、Obsidian
Sistema de archivosFilesystem (lectura/escritura de archivos locales)

El SDK oficial cubre los siguientes lenguajes de programación: TypeScript, Python, C#, Java, Swift.

En el desarrollo real, en la mayoría de los escenarios basta con buscar un servidor ya existente y usarlo. Solo cuando se necesita conectar sistemas internos de la empresa o bases de datos privadas es necesario escribir su propio MCP Server.


Preguntas frecuentes

PreguntaRespuesta
¿Reemplazará MCP a Function Calling? No. Function Calling es el mecanismo subyacente mediante el cual el modelo llama a las herramientas. MCP envuelve este mecanismo con un protocolo estandarizado, permitiendo que modelos de diferentes proveedores usen la misma definición de herramientas. La relación entre ambos es de "estandarización", no de "sustitución".
¿Puede un servidor usarse simultáneamente en varias aplicaciones de IA? Sí, ese es el valor principal de MCP: escriba el servidor una vez y cualquier Host compatible con MCP (Claude Code, Claude Desktop, Cursor, ChatGPT, etc.) podrá usarlo.
¿Se necesita escribir código para usar MCP? Si solo se trata de usar un MCP Server ya creado por otros, no es necesario escribir código en absoluto: basta con configurarlo en Claude Code usando el comando claude mcp add. Solo se necesita escribir código si se desarrolla su propio servidor.
¿Cómo elegir entre stdio y Streamable HTTP? Para uso personal y herramientas locales, elija stdio (configuración cero); para uso compartido en equipo y despliegue en producción, elija Streamable HTTP (requiere configurar HTTPS y OAuth).

Referencias

Otras extensiones