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

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

> **Sperimentale.** I suoi strumenti possono cambiare senza preavviso.

Beeuni offre un unico server MCP ospitato:

```text
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](/docs/it/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.

<a id="add-it-to-a-client"></a>

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

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

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

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

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

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

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

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

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

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

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

## Accesso

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

1. Una chiamata senza token restituisce `401` con `WWW-Authenticate: Bearer resource_metadata="…", scope="beeuni"`.
2. Il client legge il documento RFC 9728 all'indirizzo `/.well-known/oauth-protected-resource/v1/mcp`. Il documento indica Beeuni come server di autorizzazione.
3. Il client si registra all'indirizzo `POST /v1/oauth/register` (RFC 7591). Ottiene un client pubblico che si autentica solo con PKCE.
4. 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.
5. 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.

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

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

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

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

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

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

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

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

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

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

### Eseguire qualsiasi comando CLI

Lo strumento `beeuni` esegue la vera CLI [`beeuni`](/docs/it/cli) 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.

```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"] } }
```

- 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` | Richiedono un terminale interattivo. | `start_session`, `send_message`, `read_session`, `run_command`. |
| `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.

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

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

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

### Usa i tuoi connettori

Gli strumenti dei connettori sono la [`beeuni connectors`](/docs/it/connect/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.

1. `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.
2. `search_connector_actions` cerca un'azione in base all'intento, ad esempio
   `send an email`. `describe_connector_action` restituisce i relativi argomenti.
3. `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`.
4. 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.

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

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

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

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