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

Canonical page: https://beeuni.ai/docs/es/connect/mcp

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

Beeuni tiene un único servidor MCP alojado:

```text
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](/docs/es/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 id="add-it-to-a-client"></a>

## 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

```bash
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.

<a id="claude-desktop-and-claudeai"></a>

### 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](https://developers.openai.com/api/docs/guides/developer-mode),
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):

```json
{ "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`:

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

### Codex

```bash
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:

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

<a id="other-clients"></a>

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

<a id="sign-in"></a>

## 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:

1. Una llamada sin token recibe `401` con
   `WWW-Authenticate: Bearer resource_metadata="…", scope="beeuni"`.
2. El cliente lee el documento RFC 9728 en
   `/.well-known/oauth-protected-resource/v1/mcp`. Este identifica a Beeuni como servidor de autorización.
3. El cliente se registra en `POST /v1/oauth/register` (RFC 7591). Obtiene un cliente público que se autentica solo con PKCE.
4. 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ú.
5. 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.

<a id="revoke-a-client"></a>

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

<a id="what-a-connected-app-cannot-do"></a>

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

<a id="personal-access-token"></a>

### 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:

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

<a id="tools"></a>

## 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](#run-any-cli-command). |
| `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](/docs/es/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.

<a id="run-any-cli-command"></a>

### Ejecutar cualquier comando CLI

La herramienta `beeuni` ejecuta el [CLI](/docs/es/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.

```json
{ "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` | Requieren un terminal interactivo. | `start_session`, `send_message`, `read_session`, `run_command`. |
| `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.

<a id="project-skills"></a>

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

<a id="use-your-connectors"></a>

### Usa tus conectores

Las herramientas de conectores son la [`beeuni connectors`](/docs/es/connect/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.

1. `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.
2. `search_connector_actions` busca una acción por intención, por ejemplo
   `send an email`. `describe_connector_action` devuelve sus argumentos.
3. `call_connector` la ejecuta. El resultado indica qué `account` realizó la llamada.
   Un conector con varias cuentas y sin una predeterminada requiere `account`.
4. 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.

<a id="result-size-and-paging"></a>

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

<a id="sandboxes"></a>

### 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`.