MCP (Model Context Protocol): Guía Completa para Conectar Herramientas con IA (2026)

📋 TL;DR (Resumen Ejecutivo)

MCP (Model Context Protocol) es el estándar abierto que conecta aplicaciones de IA —Cursor, Claude, ChatGPT— con datos y herramientas externas (archivos, APIs, bases de datos) de forma unificada. En esta guía aprenderás qué es el Model Context Protocol, cómo usar un servidor MCP ya hecho en Cursor, cómo crear tu primer servidor con una Tool y un Resource, y cómo configurarlo sin quedarte atascado.

Lo que conseguirás:

• Entender qué es MCP y por qué importa (Tools, Resources, Host, Cliente, Servidor).
• Ver MCP en acción con el servidor de filesystem oficial en Cursor.
• Crear tu propio servidor MCP en Python (Tool mínima y Resource).
• Configurar mcp.json en Cursor y resolver los errores más frecuentes.

Tiempo de lectura: ~35 minutos | Nivel: Principiante a intermedio

—

📚 Tabla de Contenidos

1. Introducción
2. Qué es el Model Context Protocol (MCP)
3. Tres conceptos: Tools, Resources y Prompts
4. Arquitectura: Host, Cliente y Servidor
5. Ver MCP en acción: usar un servidor ya hecho en Cursor
6. Requisitos y entorno para crear tu primer servidor
7. Tu primer servidor MCP: una Tool mínima
8. Añadir tu servidor a Cursor (mcp.json)
9. Añadir un Resource a tu servidor
10. Ejemplo real: una Tool útil (read_file)
11. Configuración MCP en Cursor: proyecto vs global
12. Claude Desktop (opcional)
13. Buenas prácticas y seguridad
14. Troubleshooting: errores frecuentes y soluciones
15. Recursos oficiales y próximos pasos
16. Descargar ejemplos (GitHub)
17. Preguntas frecuentes
18. Conclusión

—

> 📅 Última actualización: Febrero 2026

> ✅ Verificado con: MCP SDK Python 1.2+, Cursor 2.x, especificación MCP 2025

—

Introducción {#introduccion}

Si usas Cursor, Claude o ChatGPT y quieres que la IA acceda a tus archivos, APIs o bases de datos, hay dos caminos: que cada producto implemente su propia integración (repetitiva y cerrada) o usar un estándar común. Ese estándar es el MCP (Model Context Protocol). En esta guía verás qué es el Model Context Protocol, cómo verlo en acción sin programar y cómo crear y configurar tu propio servidor MCP paso a paso, sin lagunas.

Qué necesitas antes de empezar: Cursor instalado (o Claude Desktop) y Python 3.10 o superior. Basta con saber abrir una terminal y ejecutar comandos; no hace falta conocer JSON-RPC ni STDIO — se explica cuando toque.

Qué habrás conseguido al terminar: Haber visto un servidor MCP funcionando en tu IDE, haber creado un servidor con al menos una Tool y un Resource, y saber dónde mirar cuando algo falle.

—

Qué es el Model Context Protocol (MCP) {#que-es-mcp}

MCP (Model Context Protocol) es un protocolo abierto que define cómo las aplicaciones de IA se conectan a fuentes de datos y herramientas externas. La documentación oficial lo compara con un “USB-C para IA”: un conector estándar para que cualquier aplicación compatible use cualquier servidor MCP sin integraciones a medida.

Sin MCP, cada producto (Cursor, Claude, otro IDE) tendría que implementar su propia forma de conectar con el sistema de archivos, llamar a una API o leer una base de datos. Con MCP, un servidor expone capacidades (Tools y Resources) y cualquier host (Cursor, Claude Desktop, etc.) que hable el protocolo puede usarlas.

• Especificación y documentación: modelcontextprotocol.io
• Quién lo impulsa: Anthropic (Claude), adoptado por Cursor, OpenAI y otros; es abierto y público.

Qué has conseguido: Saber qué problema resuelve MCP (conectar IA con datos y herramientas de forma estándar). A continuación verás los tres tipos de capacidades que puede ofrecer un servidor.

—

Tres conceptos: Tools, Resources y Prompts {#tres-conceptos}

Un servidor MCP puede ofrecer hasta tres tipos de capacidades. En esta guía nos centramos en Tools y Resources; Prompts se mencionan para que sepas que existen.

• Tools: El modelo decide cuándo invocarlas; la aplicación puede pedir confirmación.
• Resources: La aplicación o el usuario deciden qué recursos incluir como contexto; el modelo no “llama” al recurso, recibe su contenido.
• Prompts: No los implementamos aquí; basta con saber que un servidor puede ofrecer también plantillas de instrucciones.

Qué has conseguido: No confundir “servidor MCP” con un único tipo de capacidad; un mismo servidor puede exponer varias Tools y varios Resources. Siguiente: quién es quién en la arquitectura (Host, Cliente, Servidor).

—

Arquitectura: Host, Cliente y Servidor {#arquitectura}

Para no perderte al “añadir un servidor MCP en Cursor”, conviene tener claro quién hace qué:

• Host: La aplicación que usas (Cursor, Claude Desktop, etc.). Gestiona la sesión, la interfaz y el ciclo de vida de la conexión con los servidores.
• Cliente: El componente dentro del host que mantiene la conexión con uno o más servidores MCP. Un host puede tener varios clientes (por ejemplo, uno por servidor).
• Servidor: El proceso que expone Tools, Resources y/o Prompts. Puede ser local (comunicación por STDIO) o remoto (HTTP).

Cuando “añades un servidor MCP en Cursor”, le dices al host (Cursor) cómo arrancar el proceso del servidor (por ejemplo python server.py) y cómo hablar con él. Cursor actúa como host, usa un cliente interno para hablar con tu servidor, y tu script es el servidor.

Qué has conseguido: Entender que “añadir un servidor MCP” significa configurar el host para que lance y se comunique con ese proceso. En la siguiente sección verás el flujo completo con un servidor que no tienes que programar.

—

Ver MCP en acción: usar un servidor ya hecho en Cursor {#ver-mcp-en-accion}

Antes de escribir código conviene ver MCP funcionando. Un ejemplo sencillo es el servidor oficial de filesystem, que expone Tools para leer y escribir archivos en un directorio que tú eliges.

Requisitos: Node.js instalado (para npx). Si no lo tienes: nodejs.org.

Pasos:

1. Abrir la configuración MCP de Cursor

– Por proyecto: crea o edita .cursor/mcp.json en la raíz del proyecto que abres en Cursor.

– Global: en Linux/macOS ~/.cursor/mcp.json, en Windows %USERPROFILE%\.cursor\mcp.json.

1. Añadir el servidor filesystem

Elige un directorio que quieras exponer (por ejemplo un subdirectorio de tu proyecto). No uses la raíz del sistema por seguridad. Ejemplo de mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/ruta/absoluta/al/directorio/seguro"]
    }
  }
}

Sustituye /ruta/absoluta/al/directorio/seguro por la ruta real (en Windows usa / o \\).

1. Reiniciar Cursor por completo

Los cambios en mcp.json solo se aplican al reiniciar.

1. Comprobar que la Tool está disponible

Abre el agente (Composer) y verifica que aparecen herramientas del servidor “filesystem”. Si no ves nada, revisa la ruta en args y que npx esté en el PATH.

1. Probar con una pregunta

Por ejemplo: “Lista los archivos del directorio que configuraste” o “Lee el contenido del archivo X”. El modelo usará las Tools del servidor MCP.

Si algo falla: Comprueba que el JSON es válido (comas, comillas), que la ruta en args es absoluta y que npx existe en tu terminal. Más casos en Troubleshooting.

Qué has conseguido: Haber visto el flujo “configurar → reiniciar → usar Tool” sin escribir código. A partir de aquí construiremos nuestro propio servidor MCP.

—

Requisitos y entorno para crear tu primer servidor {#requisitos-entorno}

Para crear un servidor MCP en Python necesitas:

• Python 3.10 o superior (python3 --version).
• Entorno aislado: virtualenv o uv. Recomendamos uv: astral.sh/uv.

Con uv:

# Instalar uv (Linux/macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Crear carpeta y entorno
mkdir mcp-minimal && cd mcp-minimal
uv venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv add "mcp[cli]"

Con pip:

mkdir mcp-minimal && cd mcp-minimal
python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]"

Qué has conseguido: Entorno listo con el SDK MCP. En la siguiente sección escribiremos el primer servidor con una sola Tool.

—

Tu primer servidor MCP: una Tool mínima {#primer-servidor-mcp}

El servidor más simple es uno que expone una sola Tool. Por ejemplo, una que devuelve la hora actual. Así ves todo el ciclo: proceso que escucha por STDIO, Tool definida con tipos y docstring, y Cursor la descubre y la usa.

Crea server_minimal.py en la carpeta del proyecto (por ejemplo mcp-minimal/):

#!/usr/bin/env python3
import sys
from datetime import datetime
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("minimal")


@mcp.tool()
def get_current_time() -> str:
    """Devuelve la hora actual del sistema en formato ISO."""
    return datetime.now().isoformat()


def main():
    mcp.run(transport="stdio")


if __name__ == "__main__":
    main()

Regla crítica para servidores STDIO: El protocolo MCP usa stdout para mensajes JSON-RPC. Si tu código escribe a stdout (por ejemplo con print()), corrompes esos mensajes y el servidor deja de funcionar. Usa stderr para logs o depuración:

# ❌ Mal (STDIO)
print("Procesando...")

# ✅ Bien (STDIO)
print("Procesando...", file=sys.stderr)
# O logging (por defecto va a stderr)
import logging
logging.info("Procesando...")

Probar en terminal: Ejecuta python server_minimal.py (o uv run server_minimal.py). El proceso quedará esperando mensajes en stdin; es normal. Para usarlo de verdad lo configurarás en Cursor en la siguiente sección.

Si algo falla: Si obtienes ModuleNotFoundError: No module named 'mcp', activa el venv e instala mcp[cli]. Si el proceso termina de golpe, revisa que no haya print() a stdout.

Qué has conseguido: Un servidor MCP válido que expone una Tool. Siguiente paso: añadirlo a Cursor con mcp.json.

—

Añadir tu servidor a Cursor (mcp.json) {#anadir-servidor-cursor}

Para que Cursor use tu servidor MCP debe saber qué comando ejecutar y desde qué directorio. Eso se configura en mcp.json. Más contexto sobre Cursor y IA en el código: guía de Cursor y editores con IA en ElDiarioIA.

Ubicación: En la raíz del proyecto que abres en Cursor: .cursor/mcp.json. Si no existe la carpeta .cursor, créala.

Ejemplo con ruta absoluta al Python del venv:

{
  "mcpServers": {
    "minimal": {
      "command": "/ruta/absoluta/a/mcp-minimal/.venv/bin/python",
      "args": ["/ruta/absoluta/a/mcp-minimal/server_minimal.py"],
      "cwd": "/ruta/absoluta/a/mcp-minimal"
    }
  }
}

Sustituye /ruta/absoluta/a/mcp-minimal por la ruta real. En Windows usa el .exe del Python del venv y rutas con / o \\.

Ejemplo con uv (recomendado en la doc oficial):

{
  "mcpServers": {
    "minimal": {
      "command": "uv",
      "args": ["--directory", "/ruta/absoluta/a/mcp-minimal", "run", "server_minimal.py"]
    }
  }
}

Guarda el archivo, reinicia Cursor por completo y abre el agente (Composer). Deberías ver la herramienta get_current_time. Prueba: “¿Qué hora es según tu herramienta?”.

Si la Tool no aparece: Comprueba que las rutas en command, args y cwd son absolutas, que server_minimal.py está en cwd y que el JSON no tiene errores de sintaxis. Revisa Troubleshooting.

Qué has conseguido: Ciclo cerrado: “escribir servidor → configurar en Cursor → usar la Tool”. A partir de aquí puedes añadir un Resource.

—

Añadir un Resource a tu servidor {#anadir-resource}

Resources son datos de solo lectura que el cliente puede “leer” mediante una URI. El servidor devuelve el contenido (texto, JSON, etc.). A diferencia de una Tool, el modelo no “llama” al Resource; la aplicación o el usuario incluyen ese contenido como contexto.

Puedes añadir un Resource al mismo servidor. Ejemplo: exponer el contenido de README.md como recurso file://readme:

from pathlib import Path

BASE_DIR = Path(__file__).parent.resolve()

@mcp.resource("file://readme")
def read_readme() -> str:
    """Contenido del README del proyecto."""
    path = BASE_DIR / "README.md"
    if not path.exists():
        return "README.md no encontrado."
    return path.read_text(encoding="utf-8", errors="replace")

El cliente podrá listar recursos y leer el que tenga la URI que definas; en Cursor la forma exacta depende de la UI. Lo importante es que el servidor ofrece una Tool y un Resource.

Qué has conseguido: Entender que además de “llamar una función” (Tool) puedes “exponer un dato” (Resource). En la siguiente sección verás una Tool más útil: leer un archivo con restricción de ruta.

—

Ejemplo real: una Tool útil (read_file) {#ejemplo-real-tool}

Una Tool muy práctica es leer un archivo del proyecto. Por seguridad, limita las rutas a un directorio permitido (por ejemplo el directorio del servidor) para no exponer todo el sistema de archivos:

from pathlib import Path
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("read-file")
ALLOWED_DIR = Path(__file__).parent.resolve()


@mcp.tool()
def read_file(relative_path: str) -> str:
    """Lee un archivo del directorio del proyecto (solo rutas relativas).
    Args:
        relative_path: Ruta relativa al directorio del servidor (ej. 'src/main.py').
    """
    try:
        full = (ALLOWED_DIR / relative_path).resolve()
        if not str(full).startswith(str(ALLOWED_DIR)):
            return "Error: ruta no permitida (fuera del proyecto)."
        if not full.exists():
            return f"Error: archivo no encontrado: {relative_path}"
        if not full.is_file():
            return "Error: no es un archivo."
        return full.read_text(encoding="utf-8", errors="replace")
    except Exception as e:
        return f"Error: {e}"


def main():
    mcp.run(transport="stdio")


if __name__ == "__main__":
    main()

El modelo podrá pedir “lee el archivo src/config.py” y la Tool devolverá el contenido si está dentro de ALLOWED_DIR. Las docstrings y los type hints permiten al SDK MCP generar la descripción y el esquema de la Tool para el modelo.

Qué has conseguido: Un patrón reutilizable para exponer lógica útil (lectura de archivos, llamadas a API) como Tool, con control de seguridad. A continuación: dónde poner mcp.json (proyecto vs global) y Claude Desktop.

—

Configuración MCP en Cursor: proyecto vs global {#config-proyecto-global}

• Por proyecto: .cursor/mcp.json en la raíz del repo que abres en Cursor. Idóneo para equipos (el repo lleva su configuración MCP) o para servidores que solo tienen sentido en ese proyecto.
• Global: ~/.cursor/mcp.json (Linux/macOS) o %USERPROFILE%\.cursor\mcp.json (Windows). Los servidores estarán disponibles en todos los proyectos. Útil para herramientas personales (notas, tiempo).

Puedes combinar ambos: Cursor suele fusionar configuración de proyecto y global. Si un mismo nombre de servidor existe en los dos, suele ganar el del proyecto.

Variables de entorno (API keys, etc.): No pongas secretos en el código. Úsalos en mcp.json con la clave env:

{
  "mcpServers": {
    "mi-servidor": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/ruta/al/proyecto",
      "env": {
        "API_KEY": "tu-clave-secreta"
      }
    }
  }
}

—

Claude Desktop (opcional) {#claude-desktop}

Claude for Desktop también puede usar servidores MCP. La configuración es un JSON que depende del sistema:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

La estructura es la misma: mcpServers con command, args y, si aplica, env. Documentación: modelcontextprotocol.io (sección “Testing your server with Claude for Desktop”). En esta guía el foco es Cursor.

—

Buenas prácticas y seguridad {#buenas-practicas}

1. STDIO: no escribir a stdout. En servidores STDIO, todo lo que no sea mensajes JSON-RPC debe ir a stderr o a un archivo de log.
2. Docstrings y type hints. El SDK MCP los usa para generar la descripción y el esquema de las Tools; bien escritos mejoran el uso por el modelo.
3. Limitar alcance de Tools. Para Tools que leen o escriben archivos, restringe a un directorio permitido; no aceptes rutas arbitrarias del sistema.
4. Secretos en env. API keys y contraseñas en mcp.json → env, nunca en el código.
5. Rutas absolutas en mcp.json. Usa rutas absolutas en command, args y cwd para que funcione igual sin importar desde dónde Cursor ejecute el proceso.

—

Troubleshooting: errores frecuentes y soluciones {#troubleshooting}

—

Recursos oficiales y próximos pasos (MCP Model Context Protocol) {#recursos-oficiales}

• Especificación MCP: modelcontextprotocol.io/specification
• Quickstart Python (servidor weather): GitHub modelcontextprotocol/quickstart-resources
• Lista de servidores (Cursor): cursor.directory
• Python MCP SDK: pypi.org/project/mcp

Próximos pasos: Probar más servidores de la lista oficial, leer la spec para Resources avanzados o Prompts, y construir un servidor para tu API o tu base de datos interna.

—

Descargar ejemplos (GitHub) {#descargar-ejemplos}

El código de los tres ejemplos de esta guía está disponible en el repositorio de ElDiarioIA:

• mcp-minimal: servidor con una sola Tool (get_current_time).
• mcp-with-resource: servidor con una Tool y un Resource (file://readme).
• mcp-useful-tool: servidor con la Tool read_file (rutas relativas al proyecto).

Incluye también un ejemplo de mcp.json y un README con requisitos e instrucciones.

👉 Descargar ejemplos MCP (GitHub)

—

Preguntas frecuentes {#preguntas-frecuentes}

¿Qué es MCP en Cursor?

MCP (Model Context Protocol) en Cursor es el protocolo que permite conectar “servidores” que exponen Tools y Resources. Cursor actúa como host: arranca los servidores que configuras en mcp.json y ofrece sus capacidades al agente (Composer).

¿Necesito saber JSON-RPC para usar MCP?

No. Para usar servidores MCP solo necesitas configurar mcp.json y reiniciar Cursor. Para crear un servidor en Python, el SDK MCP (FastMCP) se encarga del JSON-RPC; tú defines funciones con @mcp.tool() y @mcp.resource().

¿Dónde pongo el archivo mcp.json para MCP en Cursor?

En la raíz del proyecto dentro de .cursor: .cursor/mcp.json. O global: ~/.cursor/mcp.json (Linux/macOS) o %USERPROFILE%\.cursor\mcp.json (Windows).

¿Por qué mi servidor MCP no aparece en Cursor?

Suele deberse a: (1) mcp.json en una ruta que Cursor no usa, (2) error de sintaxis en el JSON, (3) no haber reiniciado Cursor por completo. Comprueba la ruta, valida el JSON y reinicia.

¿Puedo usar MCP con Claude Desktop?

Sí. Claude for Desktop soporta servidores MCP. La configuración va en ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o en la carpeta de datos de Claude en Windows. La estructura es similar a Cursor (mcpServers con command y args).

¿Qué diferencia hay entre Tool y Resource en MCP?

Una Tool es una función que el modelo invoca (con aprobación del usuario): hace una acción (leer archivo, llamar API). Un Resource es un dato de solo lectura identificado por una URI que el cliente lee y pasa como contexto; el modelo no “llama” al Resource.

¿Por qué no debo usar print() en un servidor MCP?

En servidores STDIO la comunicación con el host va por stdout. Si escribes a stdout con print(), mezclas texto con los mensajes JSON-RPC y el protocolo se rompe. Usa print(..., file=sys.stderr) o un logger que escriba a stderr o a archivo.

¿Cómo paso API keys a mi servidor MCP?

No las pongas en el código. En mcp.json, en la entrada de tu servidor, añade la clave "env": "env": { "API_KEY": "tu-clave" }. El proceso del servidor recibirá esas variables de entorno.

¿Puedo tener varios servidores MCP a la vez?

Sí. En mcp.json, dentro de mcpServers, define varias entradas con nombres distintos. Cursor arrancará cada uno y el agente tendrá acceso a todas las Tools y Resources.

¿Qué versión de Python necesito para MCP?

El SDK oficial de MCP en Python requiere Python 3.10 o superior. Comprueba con python3 --version.

¿MCP funciona en Linux?

Sí. MCP es multiplataforma. Cursor y el protocolo funcionan en Linux; usa las rutas correctas en mcp.json (ej. /home/usuario/proyecto/.venv/bin/python).

¿Cómo depuro un servidor MCP que no arranca?

Ejecuta el mismo comando que pone Cursor en mcp.json desde una terminal (mismo command, args y cwd). Cualquier excepción aparecerá en stderr. Así ves el mismo entorno que usa Cursor.

¿Qué es el servidor filesystem de MCP?

Es un servidor oficial que expone Tools para leer, listar y escribir archivos en un directorio que tú indicas. Se usa con npx -y @modelcontextprotocol/server-filesystem /ruta/al/dir. Útil para que la IA acceda a archivos de un proyecto de forma controlada.

¿MCP es solo para Cursor?

No. MCP es un protocolo abierto. Cursor, Claude Desktop y otros IDEs pueden implementar el lado “host” y usar los mismos servidores MCP. Un servidor que escribas funcionará en cualquier host compatible.

¿Cómo restringir qué archivos puede leer mi servidor MCP?

En tu Tool (por ejemplo read_file), resuelve la ruta del argumento y comprueba que está dentro de un directorio permitido (ej. el directorio del proyecto). Si no, devuelve un error y no leas el archivo. En la guía, ALLOWED_DIR y str(full).startswith(str(ALLOWED_DIR)) hacen exactamente eso.

—

Conclusión {#conclusion}

Con esta guía has visto qué es el MCP (Model Context Protocol), cómo encaja en Cursor (host, cliente, servidor), cómo usar un servidor ya hecho (filesystem) y cómo crear el tuyo con una Tool mínima, un Resource y una Tool útil como read_file. Has configurado mcp.json, sabes dónde ponerlo (proyecto vs global) y tienes una tabla de troubleshooting para los fallos más habituales.

El Model Context Protocol está pensado para que cualquier aplicación de IA pueda conectarse a tus datos y herramientas de forma estándar. Si sigues los pasos de esta guía y usas los ejemplos del repo, puedes extenderla a tus propias APIs, bases de datos o flujos sin quedarte atascado. Para profundizar: especificación oficial y repositorio de ejemplos; si algo falla, vuelve a la sección de troubleshooting y revisa rutas, stdout y permisos.

—

Si te interesa llevar la IA más lejos en tu homelab, en ElDiarioIA tienes guías de LocalAI: cliente OpenAI compatible local, Flowise: framework RAG sin código y OpenClaw: asistente IA de código abierto para conectar modelos y herramientas.