INTEGRACIÓN

Asistente de IA (MCP)

Conecta Claude Code, Claude Desktop, Codex CLI o ChatGPT directamente contra tu instancia.

Guilda Work expone un servidor MCP (Model Context Protocol) con 90 tools — el mismo catálogo, definido una sola vez en mcp_tools.py, servido por dos transportes distintos según qué cliente lo consuma.

Conexión local — Claude Code, Claude Desktop, Codex CLI

mcp_server.py es un script aparte — no se empaqueta en el .exe de escritorio — así que hace falta tener Python y las dependencias del servidor instaladas:

pip install -r requirements-mcp.txt

Claude Code

Desde la carpeta del proyecto:

claude mcp add guilda-work -- python mcp_server.py

En Windows, si tienes varios Python instalados (o el de PATH no es el del .venv del proyecto, que es donde está instalado el paquete mcp), usa la ruta absoluta del intérprete para evitar que claude mcp add resuelva a un Python sin la dependencia:

claude mcp add guilda-work -- "C:\ruta\a\tu\instancia\.venv\Scripts\python.exe" "C:\ruta\a\tu\instancia\mcp_server.py"

Verifica que Claude Code lo ve con claude mcp list — debería aparecer guilda-work con estado conectado. Pídele algo simple como “lista mis menús” para confirmar de punta a punta.

Codex CLI

Añade en tu config.toml (o el equivalente que use tu instalación):

[mcp_servers.guilda-work]
command = "python"
args = ["mcp_server.py"]
cwd = "/ruta/a/tu/instancia"

Claude Desktop

Entrada equivalente en su archivo de configuración de servidores MCP (claude_desktop_config.json):

{
  "mcpServers": {
    "guilda-work": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "/ruta/a/tu/instancia"
    }
  }
}

Conector remoto — ChatGPT

ChatGPT solo admite servidores MCP remotos por HTTPS, con OAuth 2.1 real — no hay forma de conectarlo al servidor local. mcp_server_remoto.py expone exactamente las mismas 90 tools por streamable-http, delegando toda la autorización en Ory Hydra (ya desplegado como proveedor OAuth2 del resto del stack) — este proceso nunca gestiona logins ni emite tokens él mismo, solo valida cada token que llega contra la introspección de Hydra (Resource Server, no un Authorization Server propio).

1. 1

   Instala las dependencias del servidor MCP

   pip install -r requirements-mcp.txt, si no lo hiciste ya para el conector local.

2. 2

   Activa el Registro Dinámico de Cliente en Hydra

   Ya está en deploy/hydra/hydra.yml (oidc.dynamic_client_registration.enabled: true) — solo falta recrear el contenedor para que lo recoja: docker compose up -d --force-recreate hydra.

3. 3

   Define las variables de entorno

   MCP_REMOTO_ORIGIN (URL pública de este servidor), HYDRA_PUBLIC_ORIGIN (URL pública de Hydra) y opcionalmente MCP_REMOTO_PUERTO (por defecto 8017) — ver el ejemplo de abajo.

4. 4

   Publícalo detrás de Caddy

   Ya está el bloque en deploy/Caddyfile (mcp.HOSTNAME { reverse_proxy localhost:8017 }) — solo falta que Caddy recargue la configuración.

5. 5

   Arráncalo como proceso persistente

   Mismo patrón que el resto de la app fuera de Docker: copia deploy/guilda-work-mcp.service a /etc/systemd/system/, ajusta usuario/rutas, y sudo systemctl enable --now guilda-work-mcp.

6. 6

   Configura las variables de las herramientas que quieras exponer

   Cada una es opcional por separado — ver Variables de entorno para la lista completa.

7. 7

   Verifica

   curl https://mcp.tu-hostname/.well-known/oauth-protected-resource debe devolver un JSON con resource/authorization_servers (RFC9728) — confirma que el servidor sirve y anuncia Hydra como su autorización.

# .env / /etc/guilda-work.env
MCP_REMOTO_ORIGIN=https://mcp.tu-hostname
HYDRA_PUBLIC_ORIGIN=https://hydra.tu-hostname
MCP_REMOTO_PUERTO=8017

La verificación completa (ChatGPT conectándose de verdad, flujo OAuth de punta a punta) solo se puede hacer añadiendo el conector desde Ajustes → Conectores de ChatGPT una vez todo lo de arriba esté desplegado — pégale la URL pública de MCP_REMOTO_ORIGIN.

Catálogo de tools

Las tools con tenant explícito existen porque, a diferencia del resto, el aislamiento entre clientes de estas 9 herramientas no lo da una instancia compartida con permisos, sino una instancia física propia, o un token/rol/cuenta propia por tenant — sin ese parámetro no habría forma de saber qué cliente debe ver cada dato. Ver Aislamiento multi-cliente para el detalle de cada mecanismo.

Búsqueda semántica (RAG)

buscar_semantico(consulta, tenant=None) no busca coincidencias de texto exacto — convierte la consulta en un vector con un modelo de embeddings local (Ollama) y devuelve las notas, tareas y mensajes de correo más parecidos por significado, aunque no compartan ni una palabra literal con la pregunta. Útil para preguntas del tipo “¿qué dije sobre el contrato de alquiler?” cuando no recuerdas si escribiste “alquiler”, “arrendamiento” o “renta”.

buscar_semantico(consulta="problemas de facturación con un cliente")
→ encuentra notas que mencionan "impago", "retraso en el cobro" o "factura pendiente",
  aunque ninguna contenga literalmente la palabra "facturación".

Webhooks

Recibe una notificación HTTP en tiempo real cuando ocurre algo en tu cuenta (tarea finalizada, nota creada, cita reservada, correo nuevo), en vez de tener que preguntar por sondeo. Se gestionan con webhooks_listar/webhooks_crear/webhooks_borrar — ver Webhooks para el formato del payload, la firma HMAC y el catálogo completo de eventos.