> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Endpoint MCP

> Conecta Claude, ChatGPT o cualquier cliente MCP a tu cuenta

La plataforma incluye un **servidor MCP** integrado (Model Context Protocol, HTTP en streaming). Conecta una aplicación de IA —Claude, ChatGPT, Cursor o tu propio agente— y podrá gestionar asistentes, iniciar llamadas, leer transcripciones y mantener campañas en tu nombre.

```text theme={null}
https://app.famulor.io/mcp
```

En un dominio de marca blanca, el endpoint y las pantallas de inicio de sesión y consentimiento se ejecutan con la marca del inquilino. El acceso requiere la función **Connect AI / MCP** de tu plan (`connect_ai_mcp`); si no la tienes, el endpoint responde con `403`.

## Conectar clientes

<Tabs>
  <Tab title="Claude">
    1. **Configuración → Conectores → Añadir conector personalizado**
    2. Introduce `https://app.famulor.io/mcp`
    3. Claude inicia el flujo de OAuth automáticamente: inicia sesión en la página de inicio de sesión de tu plataforma y aprueba la pantalla de consentimiento.
    4. Las herramientas aparecen en Claude.
  </Tab>

  <Tab title="ChatGPT">
    1. **Configuración → Conectores → Crear** (conector personalizado)
    2. URL del servidor MCP: `https://app.famulor.io/mcp`, Autenticación: **OAuth**
    3. Inicia sesión y aprueba: las herramientas quedarán disponibles en ChatGPT.
  </Tab>

  <Tab title="Otros clientes">
    ```json theme={null}
    {
      "mcpServers": {
        "voice-ai": {
          "command": "npx",
          "args": ["mcp-remote", "https://app.famulor.io/mcp"]
        }
      }
    }
    ```

    También puedes saltarte OAuth y autenticarte con una **clave de API** (`fam_...`, creada en Configuración) como token Bearer estático: `Authorization: Bearer fam_...`
  </Tab>
</Tabs>

### Conectar desde el panel

La forma más rápida de conectar es el modal integrado **Connect AI**: abre la página **Herramientas** del panel y haz clic en **Usar en ChatGPT y Claude**. El modal muestra la URL MCP de tu cuenta (tu dominio de marca blanca, si tienes uno configurado y verificado), te deja copiarla con un clic y ofrece prompts iniciales listos para usar: crear un asistente, arreglar un asistente, analizar la última llamada, extraer datos de las últimas 30 llamadas o lanzar una campaña. **Abrir en Claude** / **Abrir en ChatGPT** envía el prompt elegido directamente a la app de IA; ahí solo te queda completar el inicio de sesión y el consentimiento.

## Autenticación

El endpoint implementa la pila de autenticación MCP moderna al completo; los clientes la gestionan automáticamente:

1. Una solicitud sin autenticar devuelve `401` con metadatos del recurso protegido (RFC 9728) y una pista `scope=`.
2. El cliente descubre el servidor de autorización (RFC 8414). El AS anuncia `client_id_metadata_document_supported: true` y `token_endpoint_auth_methods_supported` incluyendo `none` y `private_key_jwt`.
3. **Registro de cliente (prioridad MCP):** preregistrado → **Client ID Metadata Document (CIMD)** cuando `client_id` es una URL HTTPS de metadatos (Claude / ChatGPT) → Dynamic Client Registration (RFC 7591) como respaldo → manual. Luego **Authorization Code + PKCE-S256**.
4. Inicias sesión (login de marca blanca) y apruebas la pantalla de consentimiento —una vez por aplicación—; la aprobación se recuerda durante 180 días. Con CIMD, el consentimiento muestra el hostname verificado de la URL de metadatos.
5. El cliente recibe un token de acceso (`fam_at_...`, 1 h, con refresh token) y llama al endpoint.

## Herramientas disponibles

Todas las operaciones de la [REST API v1](/api-reference/introduction) también están disponibles como herramienta MCP: los mismos servicios, la misma validación (límites del plan, catálogo de modelos, lista DNC).

| Tool                                    | Scope              | Description                                                                                                                                                                                                                                                                                             |
| --------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_assistants` / `get_assistant`     | `assistants:read`  | Listar asistentes / obtener la configuración de uno                                                                                                                                                                                                                                                     |
| `create_assistant` / `update_assistant` | `assistants:write` | Crear / modificar asistentes (las actualizaciones se versionan automáticamente). Por defecto se crea en modo **Prompt único** (`flow_json` nulo). Pasa `flow_json` para usar **Flow conversacional**. Usa `list_prompt_templates` y luego `system_prompt` / `first_message` para aplicar una plantilla. |

En la app, **[Milian Copilot](/assistants/milian-copilot)** usa los mismos servicios a través de tu sesión de inicio de sesión (`/api/milian/*`), no este endpoint MCP.
\| `delete_assistant` | `assistants:write` | Eliminar un asistente de forma permanente |
\| `list_tools` / `get_tool` | `assistants:read` | Listar herramientas reutilizables (herramientas de API HTTP + servidores MCP externos) / obtener una (los secretos se muestran enmascarados como `•••`) |
\| `create_tool` / `update_tool` / `delete_tool` | `assistants:write` | Gestionar herramientas reutilizables (`type` `api`, `mcp` o `builtin`; esta última envuelve una [herramienta integrada](/assistants/built-in-tools) como herramienta del espacio de trabajo; crear/actualizar requiere una credencial de administrador porque la configuración contiene secretos) |
\| `get_assistant_tools` / `set_assistant_tools` | `assistants:read` / `assistants:write` | Leer / REEMPLAZAR las herramientas asignadas a un asistente |
\| `get_voices` | `voices:read` o `assistants:read` | Explorar la biblioteca de voces TTS (proveedor, idioma, género, acento, búsqueda) |
\| `get_models` | `assistants:read` | Explorar el catálogo de modelos (`type` = `llm`, `stt`, `tts` o `realtime`): los modelos disponibles para configurar asistentes |
\| `get_languages` | `assistants:read` | Listar los idiomas admitidos para asistentes (códigos ISO 639-1 + etiquetas) para `primary_language` / `secondary_languages` |
\| `list_calls` / `get_call` | `calls:read` | Explorar llamadas; `get_call` incluye transcripción, resumen y un `recording_url` temporal |
\| `list_history` / `get_email_history_item` | `calls:read` | Explorar llamadas y conversaciones de email agrupadas; cada turno de cliente/asistente con el mismo ID de hilo estable forma una fila y se puede consultar en orden cronológico |
\| `make_call` | `calls:write` | Iniciar una llamada saliente (`assistant_id`, `to_number`, lead opcional) |
\| `live_call_control` | `calls:write` | Control de llamadas activas: `listen_token`, `whisper`, `end_agent` o `hangup` (requiere la función de plan `live_monitoring`) |
\| `list_campaigns` / `get_campaign` | `campaigns:read` o `calls:read` | Explorar campañas, incl. configuración del marcador y número de leads |
\| `create_campaign` / `update_campaign` / `delete_campaign` | `campaigns:write` o `calls:write` | Gestionar campañas (concurrencia, reintentos, ventanas horarias de llamada y políticas de reintento: `retry_on_voicemail`, `retry_until_goal` + `goal_variable`, `mark_complete_when_no_leads`) |
\| `start_campaign` / `stop_campaign` | `campaigns:write` o `calls:write` | Iniciar o pausar el marcador |
\| `list_leads` | `leads:read` o `calls:read` | Listar los leads de una campaña |
\| `add_lead` / `add_leads` / `delete_lead` | `leads:write` o `calls:write` | Gestionar leads (individual o en bloque hasta 1000, normalizados en formato E.164 y verificados contra la lista DNC) |
\| `list_suppression_entries` | `suppression:read` o `campaigns:read` | Explorar la lista de no llamar (supresión) del espacio de trabajo |
\| `add_suppression_entry` / `remove_suppression_entry` | `suppression:write` o `campaigns:write` | Bloquear un número para todas las campañas / quitarlo de la lista |
\| `list_phone_numbers` | `phone_numbers:read` o `calls:read` | Números de la cuenta |
\| `search_phone_numbers` | `phone_numbers:read` o `calls:read` | Buscar números disponibles para comprar en el marketplace, incl. precios |
\| `buy_phone_number` / `release_phone_number` | `phone_numbers:write` o `calls:write` | Comprar / liberar números (con el flujo completo de facturación y compliance) |
\| `assign_phone_number` | `phone_numbers:write` o `calls:write` | Asignar un número a un asistente y alternar sus direcciones |
\| `list_sip_trunks` / `get_sip_trunk` | `sip_trunks:read` o `calls:read` | Explorar troncales SIP (las credenciales nunca se devuelven) |
\| `create_sip_trunk` / `delete_sip_trunk` | `sip_trunks:write` o `calls:write` | Usar tu propio operador (DID/extensión, formato de llamada, SLA avanzado) / eliminar una troncal — consulta [BYO SIP trunk](/telephony/sip-trunks) |
\| `list_knowledge_bases` / `get_knowledge_base` | `knowledge:read` o `assistants:read` | Explorar bases de conocimiento |
\| `create_knowledge_base` / `delete_knowledge_base` | `knowledge:write` o `assistants:write` | Gestionar bases de conocimiento |
\| `add_document` | `knowledge:write` o `assistants:write` | Añadir un documento (texto plano o URL de archivo) e indexarlo para su recuperación |
\| `get_balance` | `billing:read` o `calls:read` | Saldo de minutos/créditos + resumen del plan |
\| `list_transactions` | `billing:read` o `calls:read` | Historial del saldo con notas legibles; no se muestran identificadores de pago ni de conciliación |
\| `get_me` | ninguno (cualquier token válido) | Inspeccionar la credencial que llama, los límites del plan y los toggles de funciones |
\| `get_memory_settings` / `update_memory_settings` | `settings:read` / `settings:write` (o `assistants:*`) | Valores por defecto del espacio de trabajo para la memoria de quien llama (activada/desactivada por defecto + ventana de vigencia) |
\| `get_assistant_variables` / `set_assistant_variables` | `assistants:read` / `assistants:write` | Leer / REEMPLAZAR las definiciones de [variables personalizadas](/assistants/variables) de un asistente |
\| `list_integrations` / `get_integration` | `integrations:read` o `assistants:read` | Explorar [integraciones de calendario](/assistants/calendar-booking) (Cal.com, Calendly, Google, Outlook, nativa; secretos enmascarados) |
\| `create_integration` / `update_integration` / `delete_integration` | `integrations:write` o `assistants:write` | Gestionar integraciones de calendario (se prueba la conexión antes de guardar; requiere credencial de administrador) |
\| `get_assistant_integrations` / `set_assistant_integrations` | `integrations:read/write` o `assistants:read/write` | Leer / REEMPLAZAR las integraciones de calendario asignadas a un asistente |
\| `get_booking_event_types` | `bookings:read` o `assistants:read` | Listar los tipos de evento del motor de reservas (slug, duración, disponibilidad semanal) |
\| `create_booking_event_type` / `update_booking_event_type` / `delete_booking_event_type` | `bookings:write` o `assistants:write` | Gestionar los tipos de evento del motor de reservas integrado |
\| `list_bookings` / `get_booking` | `bookings:read` o `calls:read` | Explorar reservas (filtrar por tipo de evento, estado o rango de fechas) |
\| `cancel_booking` | `bookings:write` o `calls:write` | Cancelar una reserva (envía la actualización ICS `METHOD:CANCEL`) |
\| `get_usage_summary` | `calls:read` | Uso mensual de minutos de llamada |
\| `list_dashboards` / `get_dashboard` | `dashboards:read` o `calls:read` | Explorar paneles de analítica personalizados |
\| `create_dashboard` / `update_dashboard` / `delete_dashboard` | `dashboards:write` o `calls:write` | Gestionar paneles personalizados; `show_default_sections=false` crea un lienzo en blanco y `hidden_default_sections` elimina tarjetas integradas individuales (requiere la función de plan `custom_dashboards`) |
\| `get_dashboard_analytics` | `dashboards:read` o `calls:read` | KPIs, deltas de comparación, series temporales, desgloses, progreso de campañas y resúmenes de módulos restringidos |
\| `list_dashboard_widgets` | `dashboards:read` o `calls:read` | Leer widgets, filtros, configuración de visualización y diseño de la cuadrícula |
\| `create_dashboard_widget` / `update_dashboard_widget` / `remove_dashboard_widget` | `dashboards:write` o `calls:write` | Construir el lienzo del panel; eliminar lo desvincula pero conserva el widget reutilizable |

Cada herramienta acepta tanto su alcance detallado de v1 **o** el alcance general heredado (`calls:*` para campañas/leads/números/SIP/facturación/paneles, `assistants:*` para voces/conocimiento): los tokens de OAuth emitidos con los cuatro alcances estándar siguen funcionando para todo. Las claves/tokens sin restricción de alcance tienen acceso total; `:write` implica `:read`.

## Errores

| Status | Meaning                                                                    |
| ------ | -------------------------------------------------------------------------- |
| `401`  | Sin token o token no válido: el cliente debe (re)iniciar el flujo de OAuth |
| `403`  | Al plan le falta `connect_ai_mcp`                                          |
| `405`  | El endpoint no mantiene estado: usa solo `POST`                            |

<Tip>
  Las mismas funciones también están disponibles como una [REST API](/api-reference/introduction) clásica: elige la que mejor encaje con tu integración.
</Tip>