Taller MCP

Este proyecto fue desarrollado durante el taller del evento The Developers Life Weekend, en Umuarama - PR (en línea).

Sobre el taller

Repositorio con el paso a paso, código fuente y ejercicios para construir tu primer servidor basado en el Model Context Protocol (MCP).

Durante el taller, se presentaron:

• La arquitectura cliente-servidor del protocolo MCP;

• La creación y exposición de herramientas (tools) para LLMs;

• La gestión de recursos (resources) y prompts dinámicos;

• La conexión del servidor a clientes reales de IA.

El proyecto principal fue creado con Python y FastMCP. Proporciona herramientas y recursos para consultar la previsión del tiempo y demuestra una operación que pide confirmación antes de enviar invitaciones.

Related MCP server: Weather MCP Server

Requisitos

• Python 3.14 o superior;

• uv instalado;

• Una aplicación configurada en Auth0;

• Acceso a internet para consultar https://wttr.in;

• Un cliente MCP compatible, como OpenCode o MCP Inspector.

El proyecto usa uv.lock para mantener las versiones de las dependencias reproducibles.

Instalación

Clona el repositorio y entra en la carpeta del proyecto:

git clone https://github.com/marcelomarkus/tdlw-workshop-mcp.git
cd tdlw-workshop-mcp

Sincroniza las dependencias. El comando crea o actualiza el entorno virtual .venv automáticamente:

uv sync

Comprueba la versión de Python seleccionada:

python --version
uv python find

Configuración de Auth0

El servidor principal usa Auth0Provider y necesita estas variables de entorno:

Crea el archivo local de configuración a partir del modelo:

cp .env_example .env

Rellena el .env con valores reales:

AUTH_DOMAIN=https://seu-dominio.auth0.com
CLIENT_ID=seu-client-id
CLIENT_SECRET=seu-client-secret
AUDIENCE=https://sua-api

El archivo .env no se carga automáticamente con Python. Exporta las variables antes de iniciar el servidor:

set -a
source .env
set +a

O defínelas directamente en la misma llamada:

AUTH_DOMAIN="https://seu-dominio.auth0.com" \
CLIENT_ID="seu-client-id" \
CLIENT_SECRET="seu-client-secret" \
AUDIENCE="https://sua-api" \
uv run main.py

Nunca compartas el CLIENT_SECRET ni lo incluyas en commits.

Ejecutando el servidor

Con las variables cargadas, inicia el servidor principal:

uv run main.py

El endpoint MCP queda disponible en:

http://127.0.0.1:8000/mcp

Mantén el proceso en ejecución mientras el cliente MCP esté conectado. Para detenerlo, presiona Ctrl+C.

Ejecutando el MCP Inspector

El MCP Inspector proporciona una interfaz web para probar tools, resources y prompts.

En una primera terminal, inicia el servidor:

set -a
source .env
set +a
uv run main.py

En otra terminal, ejecuta el Inspector:

npx @modelcontextprotocol/inspector

Abre http://localhost:6274 en el navegador y configura:

Haz clic en Connect y prueba las herramientas y los recursos disponibles. Las variables de Auth0 deben estar en el entorno del proceso del servidor.

Conectando mediante OpenCode

El archivo opencode.json ya apunta al endpoint local:

{
  "mcp": {
    "Workshop": {
      "type": "remote",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Con el servidor en ejecución, abre OpenCode en este proyecto.

Funcionalidades disponibles

Tools

• Tempo(cidade): consulta el tiempo actual de una ciudad;

• Temperatura(cidade): consulta la temperatura actual de una ciudad;

• Enviar_Convites(quantidade): solicita confirmación y simula el envío, informando el progreso de cada elemento.

Las consultas meteorológicas usan wttr.in/<cidade>?format=%t.

Resources

• workshop://oque-o-mcp-nao-e: texto introductorio sobre MCP;

• previsao://{cidade}: previsión de una ciudad indicada en la URI.

Prompt

• exemplo_prompt(pergunta): orienta la elección entre las tools meteorológicas.

Estructura del proyecto

.
├── main.py          # Servidor MCP principal
├── mcp_com_api.py   # Servidor MCP gerado a partir da API Petstore
├── exercises/       # Exercícios progressivos do workshop
│   ├── 01-mcp-server/
│   ├── 02-resources/
│   ├── 03-tools/
│   ├── 04-prompts/
│   ├── 05-Context/
│   ├── 06-auth/
│   └── 07-mcp-api/
├── slide/            # Material de apoio
│   └── TDLW-Umuarama.pdf
├── opencode.json    # Configuração do OpenCode
├── pyproject.toml   # Metadados e dependências
├── uv.lock          # Versões resolvidas
└── .env_example     # Modelo das variáveis do Auth0

Desarrollo

Puedes ejecutar el proyecto mediante el modo Debug de VS Code o con uv:

uv run main.py

Para verificar la sintaxis de los módulos:

python -m compileall main.py mcp_com_api.py exercises

Solución de problemas

ModuleNotFoundError

Ejecuta uv sync y ejecuta el programa con uv run main.py, evitando el Python global cuando las dependencias estén instaladas solo en .venv.

Errores de autenticación

Verifica que las cuatro variables de Auth0 se hayan exportado en el mismo entorno del servidor y que el dominio incluya el protocolo esperado.

Fallo en la consulta meteorológica

Prueba la conectividad con:

curl "https://wttr.in/Sao%20Paulo?format=%t"

Puerto 8000 ocupado

Libera el puerto o ajusta el puerto en el servidor y en opencode.json, manteniendo la misma dirección en ambos lados.

Documentación y referencias

• Documentación oficial de uv

• Documentación oficial de HTTPX

• Documentación oficial de FastMCP

• Repositorio oficial del MCP SDK para Python

• Documentación oficial de MCP

• Especificación del protocolo MCP