Server MCP

Collega Claude, ChatGPT, Cursor, VS Code, Codex o qualsiasi client MCP a Beeuni tramite OAuth o un token di accesso personale. Un unico URL consente di accedere a ogni progetto che puoi aprire. Non devi installare nulla.

Sperimentale. I suoi strumenti possono cambiare senza preavviso.

Beeuni offre un unico server MCP ospitato:

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

Aggiungi questo URL a un client MCP una volta sola. La prima chiamata ti chiede di accedere a Beeuni nel browser. Dopodiché, il client opera per tuo conto, con le tue autorizzazioni, su tutti gli account e i progetti che puoi aprire: lo stesso accesso della CLI. L’URL non indica alcun progetto: gli strumenti accettano un project_id o un session_id, e list_projects li elenca. Non devi installare nulla.

Aggiungerlo a un client

Ogni client qui sotto ti fa accedere con OAuth al primo utilizzo, a meno che i passaggi non indichino un token. Non sostituire nulla: l’URL è lo stesso per tutti i progetti.

Claude Code

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

Esegui /mcp in Claude Code e accedi. Per usare invece un token di accesso personale, aggiungi --header "Authorization: Bearer $BEEUNI_TOKEN" al comando.

Claude Desktop e claude.ai

Settings → Connectors → Add custom connector. Incolla l’URL e accedi.

ChatGPT

Per usare connettori MCP personalizzati serve la modalità sviluppatore. In base alla guida alla modalità sviluppatore di OpenAI, attiva Developer mode in Settings → Security and login, poi crea un’app in modalità sviluppatore dalla pagina dei plugin di ChatGPT (pulsante più). Inserisci l’URL e scegli l’autenticazione OAuth. OpenAI indica i piani e i nomi dei menu, che possono cambiare: consulta la guida se un’etichetta è diversa.

Cursor

Usa il pulsante Add to Cursor in Connect MCP, oppure aggiungi il server a ~/.cursor/mcp.json (tutti i progetti) o a .cursor/mcp.json (un progetto):

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

VS Code

Aggiungi il server a .vscode/mcp.json. VS Code usa servers, non mcpServers, e richiede 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

Oppure modifica ~/.codex/config.toml. Per usare un token di accesso personale, indica la variabile d’ambiente che lo contiene:

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

Altri client

Aggiungi un server MCP remoto (Streamable HTTP) usando l’URL. Un client che non supporta OAuth invia un token di accesso personale come intestazione (vedi sotto).

Apri il menu dell’area di lavoro (il nome del progetto, in alto a sinistra) e seleziona Connect MCP per copiare l’URL e le istruzioni per Claude, Claude Code, Cursor e Codex.

Accesso

Il server usa il flusso OAuth 2.1 definito dalle specifiche MCP. Il client lo gestisce senza bisogno di configurazione:

Una chiamata senza token restituisce 401 con WWW-Authenticate: Bearer resource_metadata="…", scope="beeuni".
Il client legge il documento RFC 9728 all’indirizzo /.well-known/oauth-protected-resource/v1/mcp. Il documento indica Beeuni come server di autorizzazione.
Il client si registra all’indirizzo POST /v1/oauth/register (RFC 7591). Ottiene un client pubblico che si autentica solo con PKCE.
Autorizzi il client nella schermata di consenso di Beeuni. Un client registrato autonomamente è contrassegnato come Unverified app e mostra l’host a cui ti reindirizza. Autorizzalo solo se sei tu a connetterlo.
Il client scambia il codice con un token di accesso beeuni_oat_ (1 ora) e un token di aggiornamento (30 giorni, ruotato a ogni utilizzo). Quando il token di accesso scade, il client lo aggiorna senza chiedertelo di nuovo.

Revocare un client

Settings → Personal access keys → Connected apps elenca tutte le app che hai autorizzato, su tutti i tuoi account: il nome, dove effettuano l’accesso e quando sono state attive l’ultima volta. Un client MCP registrato autonomamente è contrassegnato come Unverified app. Revoke access elimina la tua autorizzazione e revoca i token: la richiesta successiva del client non andrà a buon fine e il client dovrà chiederti nuovamente l’autorizzazione. Da un terminale: beeuni tokens apps ls e beeuni tokens apps rm <client-id>. Entrambi funzionano solo da una sessione del browser o con un token di accesso personale, mai con il token dell’app stessa.

Cosa non può fare un’app connessa

L’ambito beeuni agisce per tuo conto: un’app connessa può leggere e modificare ciò che puoi leggere e modificare. Non può creare credenziali che durino più del proprio token revocabile. Per un token beeuni_oat_, questi endpoint restituiscono 403:

token di accesso personale (POST /v1/accounts/tokens) e token CLI del progetto;
chiavi gateway;
token SCIM;
client OAuth e la rotazione dei relativi segreti;
account di servizio;
l’elenco delle app connesse e la loro revoca (/v1/oauth/grants).

Revocando un client, il suo accesso termina. Un token di accesso personale è diverso: non scade, a meno che tu non passi --expires, e la revoca di un’app non lo revoca.

Token di accesso personale

Un client senza OAuth, o uno script, invia invece un token beeuni_pat_: lo stesso token usato dalla CLI. Creane uno con beeuni tokens new <name> o in Settings → Personal access keys, poi invialo come intestazione:

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

Strumenti

tools/list restituisce 23 strumenti. I parametri contrassegnati con * sono obbligatori.

Strumento	Parametri	Funzione
`list_projects`	nessuno	Elenca tutti i progetti che puoi aprire, in tutti i tuoi account, con il relativo `project_id` e il tuo ruolo.
`start_session`	`project_id`, `prompt`, `name`, `agent`	Avvia una sessione in un progetto con un primo prompt. Restituisce il `session_id`.
`send_message`	`session_id`, `text`	Accoda un messaggio a una sessione e la avvia se è ferma.
`read_session`	`session_id`*, `limit`, `wait_seconds`	Restituisce lo stato di una sessione, indicando se il turno è `idle`, `booting`, `running` o `queued`, e i messaggi più recenti con input e output di ogni chiamata agli strumenti. `limit` è 10 per impostazione predefinita, al massimo 100. `wait_seconds` (fino a 45) attende la fine del turno.
`list_sessions`	`project_id`*, `limit`, `cursor`	Elenca le sessioni visibili in un progetto: ID, titolo, stato, agente, proprietario, branch e date. `limit` è 20 per impostazione predefinita, al massimo 200.
`run_command`	`session_id`*, `command`, `cwd`, `timeout_seconds`, `job_id`, `cancel`	Esegue un comando bash nella sandbox di una sessione e restituisce stdout, stderr e codice di uscita. Un comando lungo restituisce un `job_id` su cui continuare ad attendere.
`read_file`	`path`*, `session_id`, `project_id`, `ref`, `offset`, `limit`	Legge un file dalla sandbox di una sessione oppure dal repository git di un progetto in `ref`. Le immagini vengono restituite come immagini.
`write_file`	`session_id`, `path`, `content`*, `encoding`	Scrive un file nella sandbox di una sessione e crea le directory genitrici. `encoding` è `utf8` (predefinito) oppure `base64`.
`list_files`	`path`, `session_id`, `project_id`, `ref`, `offset`	Elenca una directory della sandbox di una sessione oppure tutti i file del repository di un progetto sotto un percorso.
`read_skill`	`name`, `file`, `project_id`	Elenca le guide della piattaforma Beeuni oppure restituisce una guida (`name`) o uno dei relativi file di riferimento (`file`). Con `project_id`, le skill del progetto vengono elencate per prime; una skill del progetto `name` restituisce il relativo `SKILL.md` e i percorsi dei suoi file di riferimento.
`list_connectors`	`project_id`*, `connector`	Elenca i connettori di un progetto: slug, provider, disponibilità (`connected`, utilizzabile subito), numero di azioni e account. Con `connector`, elenca tutti gli account di quel connettore.
`search_connector_actions`	`project_id`*, `query`, `connector`, `limit`	Trova le azioni del connettore in base all’intento. Restituisce `tool` (`<connector>.<action>`), `risk` e una descrizione di una riga. Non restituisce mai gli schemi.
`describe_connector_action`	`project_id`, `tool`	Restituisce lo schema JSON Schema di input, il rischio e la descrizione di un’azione.
`call_connector`	`project_id`, `tool`, `args`, `account`, `reason`	Esegue un’azione a tuo nome. Restituisce i dati e il `account` che l’ha eseguita, un risultato `pending_approval` con il link di approvazione oppure un rifiuto con relativa motivazione.
`upload_connector_attachment`	`project_id`, `connector`, `filename`*, `content_base64` o `session_id` + `path`	Prepara un file e restituisce il riferimento `{"$beeuni_attachment": "<id>"}` da inserire in `args`.
`connect_connector`	`project_id`, `connector`, `owner`, `label`	Restituisce il link che una persona deve aprire per collegare l’account del connettore.
`search_connector_apps`	`project_id`, `query`, `limit`, `cursor`	Cerca nel catalogo delle app gestite da cui è possibile aggiungere un connettore.
`add_connector`	`project_id`*, `app` o `provider` + `slug`, `name`, `url`, `transport`, `endpoint`, `spec`, `base_url`	Aggiunge subito un connettore al progetto (registrato in `beeuni.yaml` su `main`, poi sincronizzato).
`remove_connector`	`project_id`, `connector`	Rimuove un connettore dal progetto.
`beeuni`	`args`*, `project_id`, `session_id`	Esegue la vera CLI `beeuni` a tuo nome e restituisce `exit_code`, `stdout` (o `json` per l’output `--json`) e `stderr`. Vedi Eseguire qualsiasi comando CLI.
`search_api`	`query`*, `limit`	Cerca le route dell’API Beeuni per parola chiave.
`describe_api`	`method`, `path`	Restituisce i parametri, il corpo della richiesta e lo schema della risposta di una route.
`call_api`	`method`, `path`, `project_id`, `query`, `body`	Chiama una qualsiasi route `/v1/` a tuo nome. `project_id` inserisce `{projectId}` nel percorso.

search_api, describe_api e call_api coprono tutte le funzionalità dell’app web e della CLI, perché entrambe usano la stessa API. call_api rifiuta /v1/oauth/* e qualsiasi percorso che raggiunga un endpoint MCP. Inserisci tu tutti gli altri {placeholder} nel percorso. Ogni chiamata usa la stessa autorizzazione e viene sottoposta allo stesso audit di una richiesta proveniente dall’app web. L’audit registra ogni chiamata con credential_kind: "oauth_app" e il nome dell’app connessa, perché l’API registra la credenziale con cui si è autenticata, non un’etichetta inviata dal client.

Eseguire qualsiasi comando CLI

Lo strumento beeuni esegue la vera CLI beeuni a tuo nome. Funziona con tutti i comandi CLI, quindi il server MCP ha le stesse possibilità di un terminale: segreti, trigger, cr, review, promemoria, agenti, modelli, gateway, provider, canali, sandbox, app, marketplace, file, accesso, ruoli, permessi, audit, autorizzazioni, membri, gruppi, token, fatturazione, progetti, sessioni e system-skills. Un solo strumento sostituisce circa 200 strumenti per i sottocomandi, che supererebbero il limite di strumenti di client come Cursor.

args è l’argv dopo beeuni, con un elemento dell’array per ogni argomento. Non è mai una riga di 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"] } }

Individua i comandi con ["--help"] e ["<group>", "--help"]. Aggiungi --json all’output che analizzi.
project_id imposta il progetto per un comando con ambito di progetto. session_id imposta la sessione per un comando che opera su una sessione.
Il risultato è JSON: exit_code, stdout, stderr. Con --json, l’output del comando viene restituito come valore JSON in json invece che in stdout. L’output troppo lungo viene troncato e contrassegnato con truncated; il JSON troncato non è valido, quindi restringi il comando. Un codice exit_code diverso da zero è un errore MCP. Ogni flusso viene troncato a 24.000 caratteri (stdout) e 8.000 (stderr), e il risultato lo segnala in truncated.
Un comando che dura più di circa 45 secondi viene terminato. Il risultato include timed_out.
Il server esegue al massimo 4 comandi CLI contemporaneamente. Una quinta chiamata restituisce Busy: riprova.
Sessioni, file della sandbox e connettori dispongono di strumenti dedicati (start_session, run_command, read_file, call_connector). Preferiscili.

La CLI viene eseguita sul server con il tuo token personale, usando questa API. Non riceve credenziali del server: il suo ambiente contiene solo il tuo token, l’URL dell’API, gli ID del progetto e della sessione e una home e una directory di lavoro temporanee vuote. Il server le elimina entrambe al termine del comando. Autorizzazione e audit sono gestiti dall’API: il token di un utente esterno ottiene lo stesso 403 che otterrebbe da un terminale.

Questi comandi vengono rifiutati prima dell’esecuzione. L’errore indica il motivo e l’alternativa.

Comando	Motivo	Usa invece
qualsiasi flag `--host` o `--host=`, `hosts`	Indirizza la CLI a un altro server e vi invierebbe il tuo token.	Questo server agisce già per tuo conto.
`login`, `logout`	Accesso tramite browser e token salvati.	Hai già effettuato l’accesso tramite la connessione MCP.
`init`, `ship`, `deploy`	Leggere o scrivere in una directory locale.	`run_command` in una sandbox di sessione, dove si trova il sorgente.
`tools`	Legge e modifica un `beeuni.yaml` locale, ma il server non ha una copia del progetto.	`run_command` in una sandbox di sessione: esegui `beeuni tools ls` lì.
`apps deploy`	Distribuisce una directory locale, ma il server non ne ha una.	`run_command` in una sandbox di sessione: esegui `beeuni apps deploy <path>` lì.
`env pull`, `env push`	Scrivere o leggere un file locale.	`secrets ls`, `secrets set KEY=value`.
`token`, `whoami --token-only`	Stampare il token di accesso in chiaro.	`whoami --json`.
`update`, `uninstall`	Cambiare la macchina su cui viene eseguita la CLI.	Nessuno.
`tui`, `t`, `connect`, `attach`, `sessions connect	shell	forward`
`chat` e `sessions chat` senza `--prompt`	Aprire una chat interattiva.	`start_session`, `send_message` oppure aggiungi `--prompt "<text>"`.

L’audit registra un comando CLI con le stesse credenziali di ogni altra chiamata sulla connessione (credential_kind: "oauth_app"). Non può distinguere lo strumento beeuni da call_api: entrambi raggiungono l’API con il tuo token.

Skill del progetto

read_skill con un project_id elenca le skill del progetto (i file skills/<slug>/SKILL.md del repository oppure il formato legacy .beeuni/opencode/skills/) prima delle guide della piattaforma. Passa la skill name per leggere il suo SKILL.md e i percorsi dei file di riferimento, e file per leggere un riferimento. Vedrai le skill consentite dal tuo ruolo e dalle tue autorizzazioni.

Usa i tuoi connettori

Gli strumenti dei connettori sono la beeuni connectors CLI come strumenti MCP. Chiamano gli stessi endpoint API della CLI e dell’SDK, quindi le policy dei connettori, le approvazioni e l’audit funzionano allo stesso modo su ogni interfaccia.

list_connectors mostra le connessioni attive. Un connettore con connected: false non può eseguire azioni: chiama connect_connector, apri il link restituito e poi elenca di nuovo.
search_connector_actions cerca un’azione in base all’intento, ad esempio send an email. describe_connector_action restituisce i relativi argomenti.
call_connector la esegue. Il risultato indica l’account che ha eseguito la chiamata. Un connettore con più account e senza un account predefinito richiede account.
Passa reason per una scrittura i cui argomenti sono solo ID (send_draft, eliminazione tramite ID). Chi approva lo vedrà insieme agli argomenti effettivi.

Una policy può sospendere una chiamata in attesa di approvazione. call_connector restituisce allora status: "pending_approval" con un approval_url. Una persona apre il link e approva. Richiama lo stesso strumento, con gli stessi argomenti e account, entro 15 minuti: la chiamata approvata viene eseguita una volta. Un rifiuto policy_block è definitivo.

Un risultato superiore a circa 40.000 caratteri viene restituito come anteprima contrassegnata (data_truncated). Restringi gli argomenti e richiama lo strumento. Per allegare un file, preparalo con upload_connector_attachment e inserisci il riferimento restituito in args. I connettori con provider composio non accettano riferimenti ad allegati.

Dimensioni e paginazione dei risultati

Il risultato di uno strumento viene troncato a 60.000 caratteri e termina con …[truncated at 60000 chars].
read_file restituisce un file di testo lungo in pagine di circa 50.000 caratteri al massimo. Un risultato troncato termina con il offset che permette di continuare. offset salta delle righe e limit limita il numero di righe restituite. Un file binario non viene restituito come testo: leggilo con run_command.
list_files tronca allo stesso modo un elenco lungo. Passa il offset indicato.
list_sessions restituisce next_cursor quando sono disponibili altre sessioni. Passalo di nuovo come cursor.
read_session restituisce gli ultimi messaggi limit. Tronca ogni input e output degli strumenti e rimuove i messaggi più vecchi se il risultato non rientra nei limiti (omitted_older). last_turn_error indica un turno non riuscito.
Una richiesta MCP riceve risposta entro 55 secondi. read_session con wait_seconds e una sandbox ancora in avvio si interrompono entrambi prima: richiama lo strumento.

Sandbox

run_command, read_file, write_file e list_files con un session_id accedono alla sandbox attiva della sessione, proprio come fanno il terminale web e il pannello dei file. I percorsi relativi vengono risolti sotto /workspace, la copia Git del progetto associata alla sessione. Una sandbox arrestata si avvia alla prima chiamata. La CLI beeuni nella sandbox è connessa come la sessione. Con un project_id e senza session_id, read_file e list_files leggono il repository Git del progetto senza avviare alcuna sandbox.

Un comando può durare diversi minuti. Una chiamata allo strumento attende circa 50 secondi. Se il comando è ancora in esecuzione, run_command restituisce status: running, un job_id e l’output prodotto fino a quel momento. Chiama run_command con quel job_id per continuare ad attendere, oppure con cancel: true per interromperlo. timeout_seconds (predefinito: 600, massimo: 86400) interrompe i comandi troppo lunghi, con codice di uscita 124. L’output viene conservato in ~/.cache/beeuni-mcp/jobs/<job_id>/ nella sandbox; il risultato dello strumento mostra gli ultimi 24.000 byte di ciascun flusso. Quando una sandbox si arresta, anche i comandi in esecuzione vengono interrotti.

Il server è stateless: risponde a POST con JSON e a GET e DELETE con 405.