Saltar al contenido
Desarrolladores
9 min de lectura

Referencia de herramientas de agente y MCP

Todas las herramientas que el servidor MCP de Furcata expone a los agentes de IA, con niveles de acceso, parámetros y límites.

Compartir artículo

El servidor MCP de Furcata expone tu cuenta a agentes y asistentes de IA a través del Model Context Protocol. Un agente se conecta una vez, descubre las herramientas que tiene permitido usar y luego las llama en tu nombre.

Esta página es la referencia completa de herramientas. Cada herramienta corresponde a un endpoint REST documentado, así que aplican las mismas reglas de autorización por cuenta.

Conexión

El endpoint de MCP es una sola dirección HTTPS. Habla JSON-RPC sobre el transporte Streamable HTTP y responde cada solicitud con un único cuerpo JSON.

  • Endpoint: https://api.furcata.com/v0/mcp
  • Método: solo POST. GET y DELETE devuelven 405 con un encabezado Allow: POST.
  • Autenticación: un encabezado Authorization: Bearer YOUR_FURCATA_TOKEN que lleva un token de acceso OAuth o un token de acceso de Furcata.
  • Content-Type: application/json, con Accept: application/json, text/event-stream.

El transporte no tiene estado. No hay sesión que mantener abierta ni Mcp-Session-Id que devolver, así que un cliente puede hacer cada llamada de forma independiente.

list-tools.sh
curl -X POST https://api.furcata.com/v0/mcp \
  -H "Authorization: Bearer YOUR_FURCATA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Niveles de acceso

Cada herramienta declara el rol que necesita quien llama sobre la cuenta de destino. La autorización se evalúa por cuenta, no de forma global, así que la misma persona puede ser propietaria de una cuenta y miembro de otra.

  • member — cualquier principal autenticado. El manejador REST subyacente igual limita el resultado a lo que ese principal puede ver.
  • admin — quien llama debe ser administrador o propietario de la cuenta indicada en account_id.
  • owner — quien llama debe ser el propietario de la cuenta indicada en account_id.

Quien llama y está autenticado pero no tiene el rol requerido recibe un error JSON-RPC y la herramienta nunca se ejecuta.

Herramientas de lectura

Las herramientas de lectura nunca cambian datos ni generan costo de mensajería. Son seguras para que un agente las llame libremente dentro de los límites de peticiones.

  • account_list — lista las cuentas activas que administra el principal autenticado. Llámala primero para descubrir el account_id que necesitan las demás herramientas.
  • account_get — devuelve el perfil de una cuenta: alias, nombre, país, idioma, dominio, estado e imagen.
  • account_user_list — lista los usuarios vinculados a una cuenta con el rol que tiene cada uno.
  • contact_list — lista los contactos recientes, incluidos idioma, nombre, correo electrónico, id externo, nota y estado de baja.
  • service_list — lista metadatos de servicios acotados a la cuenta. No se incluyen mapas operativos de contactos, listas de destinatarios, plantillas ni credenciales.
  • message_list — lista los mensajes entrantes y salientes más recientes, opcionalmente filtrados por dirección.
  • hook_list — lista las suscripciones de webhook registradas en una cuenta para las transiciones de estado de los mensajes.
  • report_account_usage — devuelve el reporte de uso y costo de mensajería de una sola cuenta.
  • report_accounts_usage — devuelve el reporte agregado de uso y costo de todas las cuentas que posee el principal.

Herramientas de escritura

Las herramientas de escritura cambian datos de la cuenta. Ninguna envía un mensaje ni gasta dinero, así que es seguro reintentarlas.

  • contact_sync — crea o combina un contacto. Los campos opcionales omitidos conservan sus valores existentes. Un número de teléfono con formato inválido se omite en silencio en lugar de hacer fallar la llamada.
  • contact_count — recalcula los totales de contactos de un servicio y los guarda en el documento del servicio. No se crea, modifica ni elimina ningún contacto.
  • message_archive — archiva la conversación con un contacto y registra qué usuario realizó la acción, con la opción de marcar al contacto como dado de baja al mismo tiempo.
  • account_status — cambia el estado del ciclo de vida de una cuenta. Los propietarios y administradores solo pueden alternar una cuenta ya activa entre active y paused.
  • number_find — busca en el catálogo del proveedor de telefonía los números disponibles para comprar. La búsqueda no selecciona ni compra nada.
  • hook_create — suscribe un endpoint HTTPS a un evento de transición de estado de mensaje en una cuenta.

Herramientas que envían o eliminan

Dos herramientas están marcadas como destructivas porque su efecto no se puede deshacer. Un agente debe confirmar con una persona antes de llamar a cualquiera de las dos.

  • message_send — pone en cola un mensaje SMS, MMS o de WhatsApp para uno o más destinatarios. Los mensajes se despachan desde la cola de entrega y no se pueden retirar una vez en cola.
  • hook_delete — elimina de forma permanente una suscripción de webhook de una cuenta. Requiere el rol de propietario de la cuenta.

message_send no crea contactos de forma implícita. Cada destinatario debe existir ya como contacto, así que llama primero a contact_sync para un número nuevo. Enviar a un número desconocido falla con un error de precondición en lugar de crear un registro en silencio.

send-message.sh
curl -X POST https://api.furcata.com/v0/mcp \
  -H "Authorization: Bearer YOUR_FURCATA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "message_send",
      "arguments": {
        "account_id": "acc_123",
        "recipients": ["+15555550100"],
        "body": "Your appointment is confirmed.",
        "idempotency_key": "YOUR_IDEMPOTENCY_KEY_16_CHARS"
      }
    }
  }'

Parámetros de las herramientas

Las herramientas más usadas reciben los siguientes argumentos. Toda herramienta que actúa sobre una cuenta requiere account_id.

  • contact_sync — phone (obligatorio), email, externalId, firstName, lastName, note, unsubscribed, language.
  • message_send — recipients (obligatorio, E.164), body, media, template, type (sms, mms o whatsapp; por defecto sms), language, idempotency_key.
  • message_list — direction (inbound u outbound).
  • hook_create — target_url (debe empezar con https://) y event (message.delivered, message.failed o message.inbound).
  • hook_delete — hook_id.
  • message_archive — contact (obligatorio) y unsubscribe (por defecto false).
  • contact_count — service (obligatorio).
  • account_status — status (active, inactive, suspended, paused, draft o review).
  • number_find — type (local o tollFree; por defecto local), areaCodes, country, area, latitude, longitude, distance, placeId.
  • report_account_usage y report_accounts_usage — from y to (ISO-8601 UTC), created, direction, type, country, language, sentiment.text, contact, service y sort.

Límites

  • Llamadas a herramientas: 60 por minuto por principal, por instancia en ejecución.
  • Llamadas a herramientas de escritura: 15 por minuto por principal, por instancia en ejecución.
  • Solicitudes anónimas al transporte: 120 por minuto por dirección de cliente.
  • Cuerpo de la solicitud: 1 MB.
  • Plazo del gateway: 120 segundos.

Como el servicio escala horizontalmente, el techo efectivo es el presupuesto por instancia multiplicado por el número de instancias en ejecución. Trátalos como límites de radio de impacto y no como una cuota fija.

Errores

MCP reporta las fallas en dos lugares distintos, y la diferencia importa al decidir si reintentar.

  • Un error JSON-RPC significa que la herramienta nunca se ejecutó. Cubre un token ausente o inválido, un nombre de herramienta desconocido, argumentos que no pasan la validación del esquema, un rol insuficiente y el límite de peticiones.
  • Un resultado de tools/call con isError en true significa que la herramienta se ejecutó y rechazó. La llamada REST subyacente devolvió un estado no exitoso y su mensaje se transmite tal cual.

Un token ausente o inválido devuelve HTTP 401 con un encabezado WWW-Authenticate que apunta a los metadatos del recurso protegido, lo que permite que un cliente compatible con OAuth inicie el flujo de autorización por su cuenta.

Cada llamada queda auditada

Cada llamada a una herramienta emite un registro de log estructurado: el usuario que actúa, los argumentos con los valores sensibles ocultos, el resultado, el estado y la duración. Si la llamada la hace una automatización, también se registra el identificador de la automatización.

Qué no está disponible

Algunas capacidades se omiten deliberadamente de la superficie de MCP. Siguen disponibles a través de la API REST y del panel.

  • Gestión de plantillas.
  • Agregar o quitar números de teléfono.
  • Agregar, quitar o cambiar el rol de usuarios.
  • Crear, editar o eliminar servicios.
  • Búsqueda de ubicaciones y mapas.
  • Configuración de IA, que se omite porque es un riesgo de inyección de prompts.
  • Dominio, alias y creación de cuentas.
  • Generación de video con IA.

Próximos pasos

Lee la página del servidor MCP para el recorrido de conexión, luego revisa autenticación para obtener tokens y errores e idempotencia antes de dejar que un agente envíe algo.