# Guapu — referencia completa para agentes IA

Guapu es un CRM multi-tenant AI-native para PYMEs de LATAM. Esta es la referencia completa de cómo un agente IA se conecta y qué puede hacer. Caminos: MCP (tools + resources + prompts), GPT Actions, API REST, ACP y A2A.

## 1. Conexión MCP (recomendado para Claude / Cursor / clientes MCP)

- Endpoint: `https://guapu.io/api/mcp`
- Métodos JSON-RPC 2.0: `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`, `ping` · `POST` (single + batch) · `GET` (manifiesto de descubrimiento) · `OPTIONS` (CORS)
- Auth (cualquiera de las dos):
  - **OAuth 2.1** (recomendado, 1 clic): el cliente MCP descubre `https://guapu.io/.well-known/oauth-protected-resource`, registra (`POST /api/mcp/oauth/register`, RFC 7591), autoriza (`GET /api/mcp/oauth/authorize`, PKCE S256), canjea (`POST /api/mcp/oauth/token`). El access_token ES una scoped key `gk_live_…`.
  - **API key**: `Authorization: Bearer gk_live_…` o `?key=gk_live_…`. Se crea en `https://guapu.io/desarrolladores`.
- Scopes: `read` (lectura) · `write` (escritura). Rate-limit: 120 req/min por key.
- Registro MCP: `https://guapu.io/.well-known/mcp/server.json`.

### Herramientas MCP (tools) — 39
Lectura: `whoami`, `list_contacts`, `get_contact`, `list_deals`, `get_deal`, `list_pipelines`, `report_conversion_by_stage`, `dashboard_summary`, `search_knowledge`, `list_knowledge`, `list_conversations`, `get_conversation`, `list_surveys`, `get_survey`, `list_quotes`, `get_quote`, `quote_analytics`, `list_sequences`, `list_calendar_events`, `list_forms`, `list_automations`, `list_flows`, `list_agent_activity`.
Escritura: `create_contact`, `update_contact`, `create_deal`, `update_deal`, `move_deal_stage`, `add_knowledge`, `update_knowledge`, `archive_knowledge`, `reply_to_conversation`, `create_quote`, `send_quote`, `quote_and_send`, `create_client_space`, `create_calendar_event`, `enroll_in_sequence`, `create_survey`.
Toda herramienta de escritura acepta `idempotency_key` (reintentar con la misma clave NO duplica la operación). Las creaciones (`create_deal`, `create_quote`, `create_calendar_event`, `enroll_in_sequence`, `create_survey`) además aceptan `dry_run: true` para previsualizar sin ejecutar.

### Recursos MCP (resources)
El agente puede LEER contexto de la cuenta sin llamar una tool (con `resources/read`):
`guapu://account`, `guapu://pipelines`, `guapu://dashboard`, `guapu://conversion`, `guapu://knowledge`.

### Prompts MCP (plantillas listas)
Descubre con `prompts/list`, carga con `prompts/get`:
`qualify_lead` (califica un lead), `draft_followup` (redacta un seguimiento), `summarize_account` (resumen del CRM), `weekly_report` (reporte semanal), `handle_new_lead` (playbook de lead nuevo).

Ejemplos de uso (lenguaje natural que un agente traduce a tools):
- "Cotiza 1 mes de mentoría + comunidad para el contacto X y mándaselo por WhatsApp" → `quote_and_send(channel:"whatsapp")`.
- "¿Cuántos negocios tengo en la etapa de negociación?" → `list_deals(stage_id:…)`.
- "¿El cliente abrió la cotización COT-0042?" → `quote_analytics`.
- "¿Qué citas tengo esta semana?" → `list_calendar_events`.

## 2. GPT Actions (ChatGPT)

Usa la especificación OpenAPI 3.1 en `https://guapu.io/api/v1/openapi` como el schema de un GPT Action. Auth: API key `gk_live_…` (Bearer) o `X-Api-Key`. Manifiesto de plugin: `https://guapu.io/.well-known/ai-plugin.json`.

## 3. API REST v1 (n8n / Zapier / agentes propios / scripts)

Base: `https://guapu.io/api/v1`. Auth: `Authorization: Bearer gk_live_…`.
Recursos: `/contacts`, `/deals`, `/pipelines`, `/reports/conversion-by-stage`, `/webhooks`, `/me`. Docs interactivas: `https://guapu.io/api/v1/docs`. OpenAPI: `https://guapu.io/api/v1/openapi`.

## 4. A2A + lenguaje natural (cualquier cliente, sin function-calling)

- Agent Card (protocolo A2A): `https://guapu.io/.well-known/agent-card.json` (alias `https://guapu.io/.well-known/agent.json`).
- Endpoint: `https://guapu.io/api/a2a`. Auth: `Authorization: Bearer gk_live_…`. `GET` devuelve la Agent Card.
- `POST` acepta A2A JSON-RPC `message/send` (respuesta única), `message/stream` (eventos SSE en vivo), `tasks/get` (recupera una tarea previa por id), o la forma simple `{"message":"cotiza 1 mes para el contacto de Juan y mándasela por WhatsApp"}`. Las respuestas devuelven un `taskId` consultable luego con `tasks/get`.
- Ejecuta tus herramientas en lenguaje natural (loop acotado a 5 pasos; respeta el scope de la key, el modo solo-lectura y el kill-switch; las acciones de dinero siguen apagadas por defecto). Ideal para clientes que no hacen function-calling.

## 5. Compras agénticas (ACP — Agentic Commerce Protocol)

Manifiesto: `https://guapu.io/api/acp`. Feed de catálogo + checkout sessions para que un agente compre en el catálogo del tenant. (Modo test por defecto.)

## Seguridad y aislamiento
- La organización (cuenta) SIEMPRE se resuelve desde la API key, nunca de los argumentos → un agente solo ve/opera los datos de SU cuenta (anti-IDOR, RLS).
- No hay herramientas para tocar el código, la configuración de la plataforma ni otras cuentas.
- Acciones que mueven dinero (reembolsar/cancelar pedido) están triple-gateadas y por defecto OFF.
- Kill-switch por cuenta (`mcp_enabled`) y modo solo-lectura (`mcp_readonly`). Cada llamada queda en un log de auditoría.