Pilota betool desde Claude (servidor MCP)

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.

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.
• 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.

Crear una clave MCP

Reservado a los administradores de la organización: una clave conlleva autoridad sobre toda la organización.

1. En betool, abre Ajustes → MCP.
2. 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.
3. 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.

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.

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:

1. En la aplicación, añade el servidor MCP https://platform.betool.ai/mcp.
2. 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.
3. Elige el ámbito que concedes y pulsa Autorizar. La aplicación nunca recibe más de lo que marcas, aunque haya pedido más.

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 → 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 → MCP, estrictamente acotado a tu organización.

Próximamente

• Control de grano fino, por herramienta, de la superficie expuesta por MCP.
• Flujo servidor→cliente (SSE) para las notificaciones del servidor.

Consulta también

• API de administración — automatiza betool desde tus propios sistemas.
• Seguridad y conformidad — el modelo de gobernanza de propuestas.