MCP Certificate

MCP Certificate (Curso Guiado)

Repositorio de una clase guiada sobre Model Context Protocol (MCP). Incluye cuadernos por capítulos, ejemplos prácticos y material de referencia para aprender a:

• Entender qué es MCP y sus implicaciones de seguridad.
• Integrar MCPs en herramientas como Gemini CLI y Windsurf.
• Crear tu propio servidor MCP con FastMCP, incluyendo generación desde un OpenAPI y pruebas locales.

Prerrequisitos

Conocimientos previos

• Python básico: familiaridad con pip, entornos virtuales y ejecución de scripts
• Git: conocimientos básicos de clonado de repositorios y control de versiones
• JSON/REST APIs: comprensión de APIs REST y formato JSON (para Chapter 3)
• Terminal/línea de comandos: comodidad ejecutando comandos en terminal

Software requerido

1. UV (gestor/runner de Python)

Propósito: gestión de dependencias y ejecución de módulos mcp de python.

Instalación: Accede a https://docs.astral.sh/uv/getting-started/installation/#installation-methods e instala para tu sistema operativo.

Verificación:

uv --version

2. Git

Propósito: clonar el repositorio.

Instalación:

• Descarga desde https://git-scm.com/download/win
• Durante la instalación, acepta las opciones por defecto
• Asegúrate de marcar "Git from the command line and also from 3rd-party software"

Verificación:

git --version

3. Windsurf Editor

Propósito: editor con IA integrada para trabajar con MCPs en el entorno Cascade y seguir este curso guiado.

Instalación:

• Descarga desde https://windsurf.com/download
• Instala siguiendo el asistente por defecto

Configuración inicial:

• Al abrir por primera vez, configura tu cuenta si es necesario
• Instala las extensiones recomendadas para Python y Jupyter.

4. Node.js (versión LTS)

Propósito: ejecutar herramientas MCP escritas en JavaScript, MCP Inspector, gemini-cli y Claude Desktop.

Instalación:

• Descarga la versión LTS desde https://nodejs.org/
• IMPORTANTE: Durante la instalación, marca "Add to PATH" para poder usar node y npm desde terminal
• Acepta instalar herramientas adicionales cuando se solicite

Verificación:

node --version
npm --version

Configuración adicional (recomendado):

# Actualizar npm a la última versión
npm install -g npm@latest

5. Docker Desktop (opcional)

Propósito: ejecutar MCPs en contenedores para mayor aislamiento y seguridad.

Instalación:

• Descarga desde https://www.docker.com/products/docker-desktop
• Ejecuta el instalador y reinicia el sistema si se solicita
• Inicia Docker Desktop tras la instalación

Verificación:

docker --version
docker compose version

Configuración del proyecto

Paso 1: Clonar el repositorio

git clone https://github.com/SergiFuster/MCP-certificate.git
cd MCP-certificate

Paso 2: Configurar entorno Python

# Crear entorno virtual con UV
uv venv

# Sincronizar e instalar todas las dependencias
uv sync

Paso 3: Verificar instalación

# Verificar que FastMCP está disponible
uv run fastmcp --help

# Verificar que Jupyter está disponible para los notebooks
uv run jupyter --version

Paso 4: Abrir el proyecto

# Abrir con Windsurf (si está en PATH)
windsurf .

# Alternativa: abrir Windsurf manualmente y seleccionar la carpeta del proyecto

APIs y claves necesarias

Para completar todos los ejercicios del curso necesitarás las siguientes claves API (puedes obtenerlas durante el curso):

• Brave Search API: para el Chapter 2 (MCP de búsqueda web)

- Registrarse en: https://api.search.brave.com/ - Variable de entorno: BRAVE_API_KEY

• Context7 API (opcional): para integración con Windsurf en Chapter 2

- Registrarse en: https://context7.com/ - Variable de entorno: CONTEXT7_API_KEY

• OpenAI/Anthropic/Google (opcional): para TaskMaster AI en Chapter 2

- Configurable con múltiples proveedores

Resolución de problemas comunes

Error de permisos en Windows:

# Ejecutar PowerShell como administrador si hay problemas de permisos
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

UV no encontrado tras instalación:

• Reinicia la terminal
• Verifica que esté en PATH: echo $env:PATH (PowerShell) o echo %PATH% (CMD)

Node.js no encontrado:

• Reinicia la terminal tras la instalación
• Verifica que esté en PATH

Docker no inicia:

• Asegúrate de que la virtualización esté habilitada en BIOS
• En Windows, habilita WSL2 si se solicita

Índice

• Prerrequisitos
• Qué son los MCP — Chapter1/
• Casos de uso — Chapter2/
• FastMCP: crea tu servidor MCP — Chapter3/
• Cómo ejecutar los ejemplos
• Estructura del repositorio
• Referencias

Qué son los MCP — Chapter1/

Contenido en Chapter1/chapter_1.ipynb.

• Conceptos: introducción a MCP y su rol como puente entre LLMs y herramientas/servicios.
• Seguridad: MCP abre la puerta a prompt injection si no se gestiona bien. Recomendaciones:

- Usar implementaciones oficiales. - Probar MCPs y auditar respuestas. - Usar claves con permisos/alcance mínimos. - Trabajar con cuentas/repositorios con información limitada.

• Cómo inspeccionar MCPs:

- Uso de MCP Inspector (npx -y @modelcontextprotocol/inspector). - Diferencias entre MCP tipo STDIO (se ejecutan como procesos locales con command/args/env) y MCP tipo HTTP (servidor accesible por red con SSE/headers).

Casos de uso — Chapter2/

Contenido en Chapter2/chapter_2.ipynb.

• Gemini CLI: instalación y uso de MCPs desde la CLI de Google Gemini.

- Ejemplos de configuración para MCPs de terceros como Obsidian y Brave Search.

• Obsidian MCP: configuración vía uvx mcp-obsidian y variables de entorno (API Key, host/puerto).
• Brave Search MCP: configuración vía npx @brave/brave-search-mcp-server con BRAVE_API_KEY.
• Windsurf: instalación y configuración de MCPs dentro del chat de Cascade.

- Context7: servidor HTTP con serverUrl y header CONTEXT7_API_KEY. - TaskMaster AI: servidor STDIO via npx task-master-ai con múltiples API Keys soportadas; selección de modelo y uso en el chat.

FastMCP: crea tu servidor MCP — Chapter3/

Contenido en Chapter3/chapter_3.ipynb y ejemplos en Chapter3/src/.

• Crear un servidor básico (FastMCP):

- Chapter3/src/mcp_server_example.py define un servidor sencillo con un tool greet(name: str). - Ejecución típica:

    # Desde la raíz del repo (tras uv sync)
    cd Chapter3/src/
    fastmcp run mcp_server_example.py:mcp
    # HTTP (opcional)
    fastmcp run mcp_server_example.py:mcp --transport http --port 8000

• Probar el servidor (cliente FastMCP):

- En el notebook Chapter3/chapter_3.ipynb hay un ejemplo con Client("http://localhost:8000/mcp") que llama al tool greet.

• Generar un servidor MCP desde un OpenAPI:

- Chapter3/src/mcp_server_from_openapi_spec.py muestra cómo: 1) Cargar openapi.json de un API (ej. un FastAPI local) y 2) Crear un servidor MCP con FastMCP.from_openapi(...) usando un httpx.AsyncClient. - Requisitos: que el API objetivo esté corriendo y accesible.

• Servidor FastAPI de ejemplo:

- Chapter3/src/fastapi_server_example.py implementa CRUD en memoria con FastAPI. - Exporta OpenAPI en http://127.0.0.1:8000/openapi.json al levantar el servidor.

Cómo ejecutar los ejemplos

Antes de empezar, asegúrate de haber hecho uv sync y de estar usando el entorno (source .venv/bin/activate si no usas uv run).

• FastAPI (CRUD + OpenAPI):

1. Instala Uvicorn si hace falta:

     uv add "uvicorn[standard]"

2. Ejecuta el servidor de ejemplo:

     uv run python Chapter3/src/fastapi_server_example.py
     # o (si tienes uvicorn):
     uv run uvicorn Chapter3.src.fastapi_server_example:app --reload --host 127.0.0.1 --port 8000

3. Verifica: - Salud: http://127.0.0.1:8000/health - OpenAPI: http://127.0.0.1:8000/openapi.json

• FastMCP (servidor básico):

  cd Chapter3/src/
  uv run fastmcp run mcp_server_example.py:mcp
  # HTTP (opcional)
  uv run fastmcp run mcp_server_example.py:mcp --transport http --port 8000

• FastMCP desde OpenAPI:

1. Asegura que un API (por ejemplo el FastAPI anterior) está corriendo en http://127.0.0.1:8000. 2. En otra terminal:

     uv run python Chapter3/src/mcp_server_from_openapi_spec.py

• Cliente de prueba (desde notebook):

- Abre Chapter3/chapter_3.ipynb y ejecuta la celda que crea Client("http://localhost:8000/mcp") y llama al tool greet.

Estructura del repositorio

Chapter1/
  chapter_1.ipynb
  src/
    comic.png
    security-schema.png
    security.jpeg
Chapter2/
  chapter_2.ipynb
Chapter3/
  chapter_3.ipynb
  src/
    fastapi_server_example.py
    mcp_server_example.py
    mcp_server_from_openapi_spec.py
pyproject.toml
README.md

Dependencias clave

Definidas en pyproject.toml:

• fastapi
• fastmcp
• ipykernel

Instálalas con:

uv sync

Referencias

• Model Context Protocol — https://modelcontextprotocol.io/docs/getting-started/intro
• Repositorio oficial de servidores MCP — https://github.com/modelcontextprotocol/servers
• Gemini CLI — https://github.com/google-gemini/gemini-cli
• Context7 — https://context7.com/
• TaskMaster AI — https://www.task-master.dev/
• FastMCP — https://gofastmcp.com/getting-started/quickstart