betool expone un servidor MCP (Model Context Protocol): un cliente MCP externo — Claude Code, Claude Desktop o cualquier aplicación compatible — puede leer la configuración de tu organización y proponer cambios en lenguaje natural (crear/editar un pipeline, un rol, una misión, una evaluación…). Es como un asistente que configura betool contigo, totalmente gobernado.
Dos formas de conectarse, al mismo endpoint https://platform.betool.ai/mcp:
- una clave API MCP en la cabecera
Authorization— lo más sencillo para Claude Code; - OAuth 2.1 + PKCE — para aplicaciones de terceros, sin manejar ningún secreto.
Nada se aplica sin una aprobación explícita. Cada cambio pasa por una propuesta. Con el ámbito Lectura + propuestas, la apruebas con un botón Aceptar y aplicar dentro de betool. Con el ámbito Completo, la aplicación puede resolver sus propias propuestas después de que aceptes en su propia conversación — el equivalente máquina de ese botón, reservado a este ámbito y auditado como todo lo demás. Elige Lectura + propuestas si quieres que la validación ocurra dentro de betool, y en ningún otro sitio.
Lo que Claude puede hacer
- Leer: inventario de modelos, el grafo y los nodos de un pipeline, los contratos de configuración de los nodos, roles/misiones, herramientas disponibles, base de conocimiento.
- Leer tus datos: las bases de datos no-code de tu organización — bases, tablas, columnas y filas. El cliente las descubre por sí mismo; una clave no puede limitarse a un subconjunto de bases.
- Proponer: mediante la herramienta
proposals.create, una propuesta de cambio pendiente — la aceptas o la rechazas en la interfaz. Esto cubre también la creación de un modelo y el lanzamiento de un benchmark (consulta Lo que se propone). - Escribir datos (ámbito Completo): crear, actualizar o reservar una fila de una de tus bases, tras tu aceptación explícita en la conversación. A diferencia de la configuración, una escritura de datos no se versiona — no se puede restaurar.
- Hablar con tus modelos (ámbito Completo): mantener una conversación de varios turnos con un modelo que hayas abierto explícitamente a los agentes externos — más abajo.
Claude descubre el contrato exacto de cada nodo (campos, valores permitidos) antes de proponer: sin adivinar, sin configuración inválida.
Los secretos de una configuración (secreto HMAC, token, contraseña) nunca le llegan: models.inspect_pipeline y las propuestas los devuelven enmascarados. Una propuesta que reenvía una configuración tal como la leyó conserva el secreto guardado, sin que la IA lo haya visto.
Las herramientas expuestas
Las herramientas se agrupan por familia. El cliente las descubre por sí mismo al conectarse; las de un conector solo aparecen si tu organización lo utiliza.
| Familia | Herramientas | Función |
|---|---|---|
models | list_models, lookup_model, list_groups, inspect_pipeline, list_contexts, get_pipeline_trace, get_exchange_metadata, automation_health, get_entry_endpoints | Inventario de modelos, lectura de un pipeline y de sus ejecuciones, estado de las automatizaciones bloqueadas |
pipeline | list_node_kinds, lookup_node_contract, lookup_module, list_all_tools, list_config_options, list_schemas, validate | Contratos de los nodos, opciones de configuración, validación de un grafo antes de proponerlo |
agents | list_roles, lookup_role, list_missions, lookup_mission | Roles y misiones de tus agentes |
benchmarks | list, get, list_check_kinds, list_runs, get_run, run_status | Escenarios de evaluación y resultados de sus runs |
knowledge | search | Búsqueda en tu base de conocimiento |
database_query / database_manage | lectura; create_row, update_row, claim_row | Tus bases no-code (escritura: ámbito Completo) |
conversation | open, send, poll, history | Hablar con un modelo (ver más abajo) |
proposals | create, describe_kind, apply, reject | Proponer un cambio, leer su contrato, resolverlo (apply / reject: ámbito Completo) |
La URL de entrada de un modelo, lista para pegar. models.get_entry_endpoints devuelve la URL pública completa de cada receptor declarado en el Start de un modelo (webhook entrante, callback de una plataforma de mensajería…) — para transmitirla a un socio sin buscar la ruta en la interfaz.
Lo que se propone
Toda modificación de configuración pasa por proposals.create(kind, payload). Antes de escribir un payload, el cliente lee su contrato exacto con proposals.describe_kind(kind). Los kinds disponibles:
| Kind | Efecto una vez aceptado |
|---|---|
model_create | Crea un modelo (proceso) — su etiqueta, su descripción, su grupo |
model_update | Modifica los metadatos de un modelo existente |
pipeline_edit | Edita el grafo de un modelo (añadir, modificar, eliminar nodos y enlaces) |
pipeline_publish | Publica el estado actual de un modelo, tras la validación previa a la publicación |
pipeline_plan | Encadena ediciones y luego una publicación sobre un mismo modelo, con una sola aceptación, de forma atómica |
role_update / mission_update | Crea o modifica un rol / una misión de agente |
knowledge_update | Crea o actualiza una ficha de texto de la base de conocimiento |
knowledge_document_replace | Sustituye el archivo de un documento de la base de conocimiento, en su lugar: mismo identificador, mismo enlace público |
database_schema_edit | Modifica la estructura de una base no-code (bases, columnas) |
benchmark_create / benchmark_update / benchmark_delete | Gestiona los escenarios de evaluación |
benchmark_run | Lanza un run de benchmark — propuesto, porque un run consume créditos |
credit_topup | Crédito manual de un saldo — reservado a la organización operadora de la plataforma, y validado por la organización acreditada |
Crear un proceso de principio a fin = varias aprobaciones. model_create crea la instancia; un pipeline_edit conecta después su Start (con sus receptores) y sus nodos; un pipeline_publish lo pone en servicio. Crear una instancia y conectarla siguen siendo dos decisiones humanas distintas.
Crear una clave MCP
Reservado a los administradores de la organización: una clave conlleva autoridad sobre toda la organización.
- En betool, abre Ajustes de la organización → MCP.
- Nombra la clave y elige su ámbito:
- Solo lectura — lee la configuración y los datos de tus bases, relee los hilos abiertos por este canal, no propone nada;
- Lectura + propuestas (recomendado) — lee y envía propuestas, que tú apruebas dentro de betool;
- Completo — también puede resolver sus propias propuestas, escribir en tus bases de datos y conversar con tus modelos, tras tu aceptación en la conversación del cliente.
- La clave en bruto se muestra una sola vez — cópiala de inmediato (nunca podrá volver a leerse). Puedes revocar una clave en cualquier momento.
Los mismos tres ámbitos existen para OAuth; allí los eliges en la pantalla de consentimiento.
Conectar Claude Code
Añade el servidor MCP de betool a Claude Code (la clave va en la cabecera Authorization):
claude mcp add betool \
--transport http \
--header "Authorization: Bearer <your-mcp-key>" \
https://platform.betool.ai/mcp
Luego pídele a Claude, en lenguaje natural: «inspecciona mi pipeline X y propón un paso que resuma el ticket antes de enviarlo». Claude lee la configuración, compone una propuesta, y tú la validas en betool.
Nunca pegues secretos en texto plano en el chat. El alcance de Claude está limitado por el ámbito de la clave, y cada llamada a una herramienta se registra en Ajustes de la organización → MCP → Registro de llamadas a herramientas (RGPD art. 15).
Hablar con tus modelos
Leer y proponer sirve para configurar betool. Una IA externa también puede usarlo: mantener una conversación real con uno de tus modelos, turno tras turno, igual que cualquier visitante en tu chat. Útil para que otra IA ponga a prueba a un asistente, para colocar betool detrás de un agente socio, o para que una herramienta interna consulte uno de tus procesos en lenguaje natural.
Cuatro herramientas: conversation.open abre o recupera un hilo, conversation.send envía un turno y devuelve la respuesta, conversation.poll recoge una respuesta que ha tardado, conversation.history relee el hilo. Ese hilo es un contexto betool como cualquier otro: aparece en tus conversaciones, el modelo ve los turnos anteriores y tú lo relees todo en la interfaz.
Autoriza el modelo, nunca la clave. Debes declarar el receptor Agente externo en el nodo Start del modelo: sin esa declaración la llamada se rechaza, incluso con una clave de ámbito Completo. Los modelos creados desde esta puesta a disposición lo declaran por defecto (el camino normal es el camino fácil); los más antiguos deben añadirlo, y a cualquiera se le puede quitar. Así que decide el modelo, nunca la clave — y el receptor debe estar presente en la versión publicada, la que se ejecuta. Y como un turno puede desencadenar efectos reales — un correo que sale, una ficha creada —, consume los créditos de la organización y queda registrado como cualquier llamada de herramienta.
Una respuesta nunca se pierde: si el modelo trabaja más tiempo que la espera concedida, la llamada devuelve un ticket y el turno sigue en el servidor — sobrevive incluso a un redespliegue. La aplicación recoge después la respuesta con conversation.poll. Reenviar el mensaje no acelera nada — y mientras el turno se ejecuta, el envío se rechaza.
Por último, este canal solo lee sus propios hilos. Un identificador de conversación procedente de otra entrada — chat público, teléfono, correo — no es legible aquí: los intercambios de tus clientes no pasan a ser consultables porque haya una aplicación MCP conectada.
Un modelo ya existente funciona sin tocarlo. Este canal coloca las mismas claves que un chat: el mensaje llega en user_message y el evento es un on_message normal — así que tus filtros y las selecciones de tus agentes siguen funcionando. Si el modelo de destino se escribió para otra entrada (lee telegram.text, un objetivo, una variable de página…), la aplicación puede aportar esas claves mediante variables: entran en el flujo donde la otra entrada las habría puesto. Lo que no puede falsificar es la identidad del turno — quién habló y por qué canal: esas claves las pone el servidor, y cualquier intento se rechaza y se informa en la respuesta.
Si el modelo se queda callado, mira su enrutamiento. Un modelo que sirve a varios canales suele ramificar según la entrada (filter input.entry_kind == chat_widget…): un turno que llega con la entrada « agente externo » no coincide con ninguna rama y nada responde — sin que se produzca ningún error. Pasa as_entry_kind para ser enrutado como ese canal. Solo cambia la clave de enrutamiento: el descriptor de canal y el registro de auditoría siguen diciendo que el turno viene de una IA externa, y se aplican las capacidades reales del canal.
Un hilo atiende un turno a la vez. Mientras el turno anterior no haya devuelto su respuesta, el siguiente se rechaza indicando el turno que debes leer. No es un límite arbitrario: una respuesta se vincula a su pregunta por su posición en el hilo, así que dos turnos en vuelo harían ambigua la atribución — mejor un rechazo claro que una respuesta plausible y falsa.
Conectar una aplicación de terceros (OAuth 2.1)
Una clave en la cabecera sirve para Claude Code. Los demás clientes — Claude Desktop, ChatGPT, un editor, tu propia aplicación — se conectan mediante OAuth 2.1 + PKCE, sin que nadie manipule un secreto. No hay nada que preparar: ningún cliente que declarar, ningún identificador que pedirnos.
Para el usuario, el recorrido son tres pantallas:
- En la aplicación, añade el servidor MCP
https://platform.betool.ai/mcp. - Tu navegador abre una pantalla de consentimiento de betool: indica la aplicación que solicita el acceso, la organización afectada y dónde se producirá el retorno. Verifica esas tres cosas — sobre todo si perteneces a varias organizaciones.
- Elige el ámbito que concedes y pulsa Autorizar. La aplicación nunca recibe más de lo que marcas, aunque haya pedido más.
Solo un administrador de la organización puede autorizar una aplicación. Conectar una crea una autoridad duradera sobre toda la organización — exactamente lo que es una clave MCP. Por tanto, un miembro con derechos limitados no puede sortear sus restricciones por esta vía.
Para los integradores, el descubrimiento es totalmente automático y conforme a los estándares: una llamada no autenticada a /mcp devuelve un 401 con la cabecera WWW-Authenticate y la dirección de nuestros metadatos (RFC 9728), que a su vez apuntan a la autorización, el intercambio de tokens, el registro dinámico del cliente (RFC 7591) y la revocación (RFC 7009). PKCE S256 es obligatorio, los tokens de acceso duran una hora y el token de refresco rota en cada uso.
# Lo que un cliente hace por sí solo — útil para comprobarlo desde un terminal.
curl -i -X POST https://platform.betool.ai/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'
# -> 401 + WWW-Authenticate: Bearer ... resource_metadata="..."
curl -s https://platform.betool.ai/.well-known/oauth-authorization-server
Un token solo es válido para betool: reutilizado en otro sitio, se rechaza (RFC 8707). Y si se presenta por segunda vez un token de refresco ya consumido — la señal de un token robado — se revoca toda la sesión y el usuario debe autorizar de nuevo.
Aplicaciones conectadas: ver y desconectar
En Ajustes de la organización → MCP, la sección Aplicaciones conectadas enumera lo que está conectado a tu organización: el nombre de la aplicación, el ámbito concedido, quién la autorizó y la fecha del último uso. Un botón Desconectar corta el acceso de inmediato — todos los tokens de esa aplicación, solo para tu organización.
Una misma aplicación puede estar conectada por varias organizaciones: desconectarla en tu caso no afecta a nadie más. Una aplicación también puede desconectarse por sí misma.
Ámbito y aislamiento
- Por defecto, una clave opera únicamente sobre tu propia organización — la organización de destino se fuerza del lado servidor; nunca pasas un id de organización como argumento.
- Las claves de proveedor (organización de backoffice) pueden apuntar a otra organización, bajo el consentimiento explícito de esa organización y con auditoría completa — útil para un caso de uso de proveedor multi-tenant.
Registro de auditoría
Cada llamada a una herramienta (externa vía MCP e interna) escribe una línea de auditoría: quién, qué herramienta, qué canal, qué ámbito, resultado, latencia. Disponible en Ajustes de la organización → MCP (sección Registro de llamadas a herramientas), estrictamente acotado a tu organización.
Consulta también
- API de administración — automatiza betool desde tus propios sistemas.
- Seguridad y conformidad — el modelo de gobernanza de propuestas.