Servidor MCP

Conecta Claude, ChatGPT, Cursor, VS Code, Codex o cualquier cliente MCP a Beeuni mediante OAuth o un token de acceso personal. Una sola URL te da acceso a todos los proyectos que puedes abrir. No tienes que instalar nada.

Experimental. Sus herramientas pueden cambiar sin previo aviso de obsolescencia.

Beeuni tiene un único servidor MCP alojado:

https://api.beeuni.ai/v1/mcp

Añade esa URL a un cliente MCP una sola vez. La primera llamada te pedirá que inicies sesión en Beeuni desde el navegador. Después, el cliente actuará como tú, con tus permisos, en todas las cuentas y proyectos que puedas abrir: el mismo alcance que la CLI. La URL no identifica ningún proyecto: las herramientas reciben un project_id o un session_id, y list_projects los enumera. No hay nada que instalar.

Añadirlo a un cliente

Todos los clientes indicados a continuación te autentican mediante OAuth la primera vez, salvo que los pasos indiquen que se necesita un token. No cambies nada: la URL es la misma para todos los proyectos.

Claude Code

claude mcp add --transport http beeuni https://api.beeuni.ai/v1/mcp

Ejecuta /mcp en Claude Code e inicia sesión. Para usar un token de acceso personal, añade --header "Authorization: Bearer $BEEUNI_TOKEN" al comando.

Claude Desktop y claude.ai

Settings → Connectors → Add custom connector. Pega la URL e inicia sesión.

ChatGPT

Los conectores MCP personalizados requieren el modo de desarrollador. Según la guía del modo de desarrollador de OpenAI, activa Developer mode en Settings → Security and login y, después, crea una aplicación en modo de desarrollador desde la página de complementos de ChatGPT (botón más). Introduce la URL y elige la autenticación OAuth. OpenAI indica los planes y los nombres de los menús, que pueden cambiar: sigue esa guía si alguna etiqueta es distinta.

Cursor

Usa el botón Add to Cursor en Connect MCP, o añade el servidor a ~/.cursor/mcp.json (todos los proyectos) o .cursor/mcp.json (un proyecto):

{ "mcpServers": { "beeuni": { "url": "https://api.beeuni.ai/v1/mcp" } } }

VS Code

Añade el servidor a .vscode/mcp.json. VS Code usa servers, no mcpServers, y necesita la extensión type:

{ "servers": { "beeuni": { "type": "http", "url": "https://api.beeuni.ai/v1/mcp" } } }

Codex

codex mcp add beeuni --url https://api.beeuni.ai/v1/mcp
codex mcp login beeuni

O edita ~/.codex/config.toml. Para usar un token de acceso personal, indica la variable de entorno que lo contiene:

[mcp_servers.beeuni]
url = "https://api.beeuni.ai/v1/mcp"
bearer_token_env_var = "BEEUNI_TOKEN"

Otros clientes

Añade un servidor MCP remoto (Streamable HTTP) con la URL. Si el cliente no puede ejecutar OAuth, envía un token de acceso personal en un encabezado (más abajo).

Abre el menú del espacio de trabajo (el nombre del proyecto, arriba a la izquierda) y selecciona Connect MCP para copiar la URL y los pasos para Claude, Claude Code, Cursor y Codex.

Iniciar sesión

El servidor usa el flujo OAuth 2.1 definido en la especificación MCP. El cliente lo gestiona sin necesidad de configuración:

Una llamada sin token recibe 401 con WWW-Authenticate: Bearer resource_metadata="…", scope="beeuni".
El cliente lee el documento RFC 9728 en /.well-known/oauth-protected-resource/v1/mcp. Este identifica a Beeuni como servidor de autorización.
El cliente se registra en POST /v1/oauth/register (RFC 7591). Obtiene un cliente público que se autentica solo con PKCE.
Apruebas el cliente en la pantalla de consentimiento de Beeuni. Un cliente autorregistrado aparece marcado como Unverified app, junto con el host al que te redirige. Apruébalo solo si lo estás conectando tú.
El cliente intercambia el código por un token de acceso beeuni_oat_ (1 hora) y un token de actualización (30 días, rotatorio con cada uso). Cuando caduca el token de acceso, el cliente lo renueva sin volver a preguntarte.

Revocar un cliente

Settings → Personal access keys → Connected apps muestra todas las aplicaciones que has aprobado en tus cuentas: su nombre, dónde inician sesión y cuándo estuvieron activas por última vez. Un cliente MCP autorregistrado aparece marcado como Unverified app. Revoke access elimina tu aprobación y revoca sus tokens: su siguiente solicitud falla y deberá volver a pedirte permiso. Desde una terminal: beeuni tokens apps ls y beeuni tokens apps rm <client-id>. Ambos funcionan solo desde una sesión del navegador o con un token de acceso personal, nunca con el token propio de una aplicación.

Qué no puede hacer una aplicación conectada

El alcance beeuni actúa en tu nombre: una aplicación conectada lee y modifica lo que tú puedes leer y modificar. No puede crear credenciales que duren más que su propio token revocable. Para un token beeuni_oat_, estas rutas responden 403:

tokens de acceso personal (POST /v1/accounts/tokens) y tokens CLI de proyecto;
claves de gateway;
tokens SCIM;
clientes OAuth y la rotación de sus secretos;
cuentas de servicio;
la lista de aplicaciones conectadas y su revocación (/v1/oauth/grants).

Revoca un cliente y perderá el acceso. Un token de acceso personal es distinto: no caduca a menos que indiques --expires, y revocar una aplicación no lo revoca.

Token de acceso personal

Un cliente sin OAuth, o un script, envía un token beeuni_pat_ en su lugar: el token que usa la CLI. Crea uno con beeuni tokens new <name> o en Settings → Personal access keys y, luego, envíalo como encabezado:

{ "mcpServers": { "beeuni": { "url": "https://api.beeuni.ai/v1/mcp", "headers": { "Authorization": "Bearer beeuni_pat_…" } } } }

Herramientas

tools/list devuelve 23 herramientas. Los parámetros marcados con * son obligatorios.

Herramienta	Parámetros	Qué hace
`list_projects`	ninguno	Muestra todos los proyectos que puedes abrir en todas tus cuentas, con su `project_id` y tu rol.
`start_session`	`project_id`, `prompt`, `name`, `agent`	Inicia una sesión en un proyecto con un primer mensaje. Devuelve el `session_id`.
`send_message`	`session_id`, `text`	Pone un mensaje en cola para una sesión e inicia la sesión si está detenida.
`read_session`	`session_id`*, `limit`, `wait_seconds`	Devuelve el estado de una sesión, si su turno está `idle`, `booting`, `running` o `queued`, y sus mensajes más recientes con la entrada y salida de cada llamada a una herramienta. `limit` es 10 de forma predeterminada, con un máximo de 100. `wait_seconds` (hasta 45) espera a que termine el turno.
`list_sessions`	`project_id`*, `limit`, `cursor`	Muestra las sesiones que puedes ver en un proyecto: ID, título, estado, agente, propietario, rama y fechas. `limit` es 20 de forma predeterminada, con un máximo de 200.
`run_command`	`session_id`*, `command`, `cwd`, `timeout_seconds`, `job_id`, `cancel`	Ejecuta un comando bash en el entorno aislado de una sesión y devuelve stdout, stderr y el código de salida. Si el comando tarda, devuelve un `job_id` para seguir esperando.
`read_file`	`path`*, `session_id`, `project_id`, `ref`, `offset`, `limit`	Lee un archivo del entorno aislado de una sesión o del repositorio git de un proyecto en `ref`. Las imágenes se devuelven como imágenes.
`write_file`	`session_id`, `path`, `content`*, `encoding`	Escribe un archivo en el entorno aislado de una sesión y crea sus directorios principales. `encoding` es `utf8` (predeterminado) o `base64`.
`list_files`	`path`, `session_id`, `project_id`, `ref`, `offset`	Muestra un directorio del entorno aislado de una sesión o todos los archivos del repositorio de un proyecto dentro de una ruta.
`read_skill`	`name`, `file`, `project_id`	Muestra las guías de la plataforma Beeuni o devuelve una guía (`name`) o uno de sus archivos de referencia (`file`). Con `project_id`, primero se enumeran las habilidades propias del proyecto; `name` de una habilidad del proyecto devuelve su `SKILL.md` y las rutas de sus archivos de referencia.
`list_connectors`	`project_id`*, `connector`	Muestra los conectores de un proyecto: slug, proveedor, si cada uno está `connected` (disponible para que lo uses ahora), cantidad de acciones y cuentas. Con `connector`, muestra todas las cuentas de ese conector.
`search_connector_actions`	`project_id`*, `query`, `connector`, `limit`	Busca acciones de conectores por intención. Devuelve `tool` (`<connector>.<action>`), `risk` y una descripción de una línea. Nunca devuelve esquemas.
`describe_connector_action`	`project_id`, `tool`	Devuelve el esquema JSON de entrada, el riesgo y la descripción de una acción.
`call_connector`	`project_id`, `tool`, `args`, `account`, `reason`	Ejecuta una acción como tú. Devuelve los datos y el `account` que la ejecutó, un resultado `pending_approval` con el enlace de aprobación o una denegación con el motivo.
`upload_connector_attachment`	`project_id`, `connector`, `filename`*, `content_base64` o `session_id` + `path`	Prepara un archivo y devuelve la referencia `{"$beeuni_attachment": "<id>"}` que debes incluir en `args`.
`connect_connector`	`project_id`, `connector`, `owner`, `label`	Devuelve el enlace que una persona abre para conectar la cuenta del conector.
`search_connector_apps`	`project_id`, `query`, `limit`, `cursor`	Busca en el catálogo de aplicaciones administradas desde el que se puede agregar un conector.
`add_connector`	`project_id`*, `app` o `provider` + `slug`, `name`, `url`, `transport`, `endpoint`, `spec`, `base_url`	Agrega un conector al proyecto ahora (se confirma en `beeuni.yaml` en `main` y luego se sincroniza).
`remove_connector`	`project_id`, `connector`	Quita un conector del proyecto.
`beeuni`	`args`*, `project_id`, `session_id`	Ejecuta el `beeuni` CLI real como tú y devuelve `exit_code`, `stdout` (o `json` para la salida `--json`) y `stderr`. Consulta Ejecutar cualquier comando CLI.
`search_api`	`query`*, `limit`	Busca rutas de la API de Beeuni por palabra clave.
`describe_api`	`method`, `path`	Devuelve los parámetros, el cuerpo de la solicitud y el esquema de respuesta de una ruta.
`call_api`	`method`, `path`, `project_id`, `query`, `body`	Llama a cualquier ruta `/v1/` como tú. `project_id` completa `{projectId}` en la ruta.

search_api, describe_api y call_api abarcan todo lo que hacen la aplicación web y la CLI, porque ambas son clientes de la misma API. call_api rechaza /v1/oauth/* y cualquier ruta que llegue a un endpoint MCP. Completa tú mismo todos los demás {placeholder} de la ruta. Cada llamada usa la misma autorización y auditoría que una solicitud de la aplicación web. La auditoría registra cada llamada con credential_kind: "oauth_app" y el nombre de la aplicación conectada, porque la API registra la credencial con la que se autenticó, no una etiqueta enviada por el cliente.

Ejecutar cualquier comando CLI

La herramienta beeuni ejecuta el CLI real de beeuni como tú. Todos los comandos CLI funcionan con ella, por lo que el servidor MCP tiene el mismo alcance que una terminal: secretos, activadores, cr, review, recordatorios, agentes, modelos, gateway, proveedores, canales, entornos aislados, aplicaciones, marketplace, archivos, acceso, roles, permisos, auditoría, concesiones, miembros, grupos, tokens, facturación, proyectos, sesiones y system-skills. Una herramienta reemplaza aproximadamente 200 herramientas de subcomandos, que superarían el límite de herramientas de clientes como Cursor.

args son los argumentos de argv después de beeuni, con un elemento de matriz por argumento. Nunca es una línea de comandos de shell.

{ "name": "beeuni", "arguments": { "args": ["--help"] } }
{ "name": "beeuni", "arguments": { "args": ["secrets", "ls", "--json"], "project_id": "<project_id>" } }
{ "name": "beeuni", "arguments": { "args": ["triggers", "ls", "--json"], "project_id": "<project_id>" } }
{ "name": "beeuni", "arguments": { "args": ["system-skills"] } }

Descubre con ["--help"] y ["<group>", "--help"]. Agrega --json a la salida que analices.
project_id establece el proyecto de un comando con ámbito de proyecto. session_id establece la sesión de un comando que actúa sobre una.
El resultado es JSON: exit_code, stdout, stderr. Con --json, la salida del comando llega como un valor JSON en json en lugar de stdout. Si la salida no cabe, se trunca y se marca con truncated; el JSON truncado no es válido, así que limita el comando. Un exit_code distinto de cero es un error MCP. Cada flujo se trunca a los 24.000 caracteres (stdout) y 8.000 (stderr), y el resultado lo indica en truncated.
Un comando que tarde más de unos 45 segundos se termina. El resultado incluye timed_out.
El servidor ejecuta como máximo 4 comandos CLI a la vez. Una quinta llamada devuelve Busy: vuelve a intentarlo.
Las sesiones, los archivos de entornos aislados y los conectores tienen herramientas específicas (start_session, run_command, read_file, call_connector). Es preferible usarlas.

El CLI se ejecuta en el servidor con tu propio token y se comunica con esta API. No recibe credenciales del servidor: su entorno solo contiene tu token, la URL de la API, los ID del proyecto y de la sesión, y un directorio temporal de inicio y de trabajo vacíos. El servidor elimina ambos directorios después del comando. La autorización y la auditoría son las de la API: el token de una persona externa obtiene el mismo 403 que desde una terminal.

Estos comandos se rechazan antes de ejecutarse. El error indica el motivo y la alternativa.

Comando	Motivo	Usar en su lugar
cualquier indicador `--host` o `--host=`, `hosts`	Dirige la CLI a otro servidor y enviaría tu token allí.	Este servidor ya actúa en tu nombre.
`login`, `logout`	Inicio de sesión en el navegador y tokens guardados.	Ya iniciaste sesión mediante la conexión MCP.
`init`, `ship`, `deploy`	Leer o escribir en un directorio local.	`run_command` en un entorno aislado de sesión, donde se encuentra el código fuente.
`tools`	Lee y edita un `beeuni.yaml` local, y el servidor no tiene una copia del proyecto.	`run_command` en un entorno aislado de sesión: ejecútalo allí con `beeuni tools ls`.
`apps deploy`	Implementa un directorio local, que el servidor no tiene.	`run_command` en un entorno aislado de sesión: ejecútalo allí con `beeuni apps deploy <path>`.
`env pull`, `env push`	Escribir o leer un archivo local.	`secrets ls`, `secrets set KEY=value`.
`token`, `whoami --token-only`	Imprimir el token de acceso sin procesar.	`whoami --json`.
`update`, `uninstall`	Cambiar la máquina que ejecuta la CLI.	Ninguno.
`tui`, `t`, `connect`, `attach`, `sessions connect	shell	forward`
`chat` y `sessions chat` sin `--prompt`	Abrir un chat interactivo.	`start_session`, `send_message` o añade `--prompt "<text>"`.

La auditoría registra un comando de la CLI con las mismas credenciales que cualquier otra llamada en la conexión (credential_kind: "oauth_app"). No puede distinguir la herramienta beeuni de call_api: ambas acceden a la API con tu token.

Habilidades del proyecto

read_skill con un project_id muestra las habilidades propias del proyecto (los archivos skills/<slug>/SKILL.md del repositorio o el .beeuni/opencode/skills/ heredado) antes de las guías de la plataforma. Pasa la habilidad name para leer su SKILL.md y las rutas de sus archivos de referencia, y file para leer una referencia. Verás las habilidades que permiten tu rol y tus permisos.

Usa tus conectores

Las herramientas de conectores son la beeuni connectors CLI como herramientas MCP. Llaman a las mismas rutas de API que la CLI y el SDK, por lo que una política de conectores, una aprobación y la auditoría funcionan igual en todas las interfaces.

list_connectors muestra qué está conectado. Un conector con connected: false no puede ejecutar acciones: llama a connect_connector, abre el enlace devuelto y vuelve a enumerar.
search_connector_actions busca una acción por intención, por ejemplo send an email. describe_connector_action devuelve sus argumentos.
call_connector la ejecuta. El resultado indica qué account realizó la llamada. Un conector con varias cuentas y sin una predeterminada requiere account.
Pasa reason en una escritura cuyos argumentos solo sean identificadores (send_draft, eliminar por ID). La persona que aprueba lo verá junto a los argumentos reales.

Una política puede retener una llamada para su aprobación. call_connector devuelve entonces status: "pending_approval" con un approval_url. Una persona lo abre y lo aprueba. Vuelve a llamar con la misma herramienta, argumentos y cuenta en un plazo de 15 minutos: la llamada aprobada se ejecuta una vez. Una denegación policy_block es definitiva.

Un resultado de más de unos 40.000 caracteres se devuelve como una vista previa marcada (data_truncated). Reduce los argumentos y vuelve a llamar. Para adjuntar un archivo, prepáralo con upload_connector_attachment y coloca la referencia devuelta en args. Los conectores con el proveedor composio no aceptan referencias a adjuntos.

Tamaño y paginación de resultados

El resultado de una herramienta se trunca a 60.000 caracteres y termina con …[truncated at 60000 chars].
read_file devuelve un archivo de texto largo en páginas de hasta unos 50.000 caracteres. Un resultado truncado termina con el offset que permite continuar. offset omite líneas y limit limita las líneas devueltas. Un archivo binario no se devuelve como texto: léelo con run_command.
list_files trunca una lista larga de la misma manera. Pasa el offset que indica.
list_sessions devuelve next_cursor cuando hay más sesiones. Devuélvelo como cursor.
read_session devuelve los últimos mensajes limit. Trunca cada entrada y salida de herramienta, y descarta los mensajes más antiguos si el resultado no cabe (omitted_older). last_turn_error indica un turno fallido.
Una solicitud MCP responde en un máximo de 55 segundos. Tanto read_session con wait_seconds como un entorno aislado que aún se está iniciando se detienen antes: vuelve a llamar.

Entornos aislados

run_command, read_file, write_file y list_files con un session_id acceden al entorno aislado activo de la sesión, igual que el terminal web y el panel de archivos. Las rutas relativas se resuelven dentro de /workspace, la copia de Git del proyecto de la sesión. Un entorno aislado detenido se inicia con la primera llamada. La CLI de beeuni en el entorno aislado inició sesión como la sesión. Con un project_id y sin session_id, read_file y list_files leen el repositorio Git del proyecto y no inician ningún entorno aislado.

Un comando puede tardar varios minutos. Una llamada a la herramienta espera unos 50 segundos. Si el comando sigue ejecutándose, run_command devuelve status: running, un job_id y el resultado obtenido hasta entonces. Llama a run_command con ese job_id para seguir esperando, o con cancel: true para detenerlo. timeout_seconds (valor predeterminado: 600, máximo: 86400) detiene los comandos que se ejecutan demasiado tiempo, con el código de salida 124. El resultado se conserva en ~/.cache/beeuni-mcp/jobs/<job_id>/ en el entorno aislado; el resultado de la herramienta muestra los últimos 24.000 bytes de cada flujo. Si un entorno aislado se detiene, también se detienen los comandos que estén ejecutándose en él.

El servidor no conserva estado: responde a POST con JSON, y a GET y DELETE con 405.