Anche in: English, Español, Português, 日本語, Deutsch, Français, 한국어, 简体中文, हिन्दी · Tutte le guide in italiano

Trasparenza: Carbon Forge è sviluppato da 100monkeys.ai, quindi leggete questa guida come il resoconto di chi lo costruisce. L'ha scritta in bozza uno dei nostri agenti di IA e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. I passi su Carbon Forge citano la documentazione pubblica, in inglese con la traduzione accanto; la configurazione di ogni client è copiata dalla documentazione di quel client, collegata accanto. L'ultima sezione elenca ciò a cui la documentazione non risponde.

Cosa state costruendo

Un workspace, più client, un token ciascuno. Il server di Carbon Forge parla Streamable HTTP, "binds every call to a workspace via a bearer token" (lega ogni chiamata a un workspace tramite un bearer token), e "tools honor the cap exactly as a human session does: there is no agent-only privilege" (gli strumenti rispettano il limite esattamente come una sessione umana: non c'è nessun privilegio riservato agli agenti) (MCP overview). Qualsiasi client che sappia inviare un'intestazione HTTP può collegarsi. Claude Code ha la sua guida: Collegare Claude Code a Carbon Forge via MCP.

Passo 1. Create un token per ogni client

Accedete su carbonforge.dev/login, aprite le impostazioni, scegliete API tokens, il workspace, un limite di ruolo e un ambito di strumenti, e "name the token after the agent or environment that will hold it" (date al token il nome dell'agente o dell'ambiente che lo terrà) (MCP tokens). Un token per client significa che il log di audit, che registra "every tool call ... under the token identity" (ogni chiamata di strumento sotto l'identità del token), vi dice quale strumento ha fatto cosa, e potete revocarne uno senza toccare gli altri.

Scegliete gli ambiti in base al lavoro (MCP token scopes): Basic LLM memory per un assistente che prende appunti, Read-only memory o SCM reader per uno che legge soltanto, SCM agent per uno che scrive codice sulle lane. La documentazione consiglia: "Default to the narrowest preset that still covers what the client needs." (Partite dal preset più ristretto che copre ancora ciò che serve al client.)

Passo 2. Tenete ogni token in una variabile d'ambiente

Il segreto "is shown once, then only the prefix." (viene mostrato una volta, poi solo il prefisso.) Entrambi i client qui sotto possono leggerlo dall'ambiente, così non finisce mai in un file di configurazione che arriva in un commit:

export CARBON_FORGE_TOKEN=‹token for this client›

Passo 3. Configurate Cursor

Cursor legge i server MCP da mcp.json: ~/.cursor/mcp.json per tutti i progetti, o .cursor/mcp.json in un solo progetto. Un server remoto accetta url e headers, e Cursor risolve ${env:NAME} in entrambi (documentazione MCP di Cursor):

{
  "mcpServers": {
    "carbon-forge": {
      "url": "https://carbonforge.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CARBON_FORGE_TOKEN}"
      }
    }
  }
}

Passo 4. Configurate Codex

Codex conserva i server MCP in ~/.codex/config.toml, o in .codex/config.toml in un progetto fidato. Un server Streamable HTTP accetta url, e bearer_token_env_var indica il "environment variable name for a bearer token to send in Authorization" (nome della variabile d'ambiente con il bearer token da inviare in Authorization) (documentazione MCP di Codex):

[mcp_servers.carbon_forge]
url = "https://carbonforge.dev/api/mcp"
bearer_token_env_var = "CARBON_FORGE_TOKEN"

Passo 5. Configurate qualsiasi altro client MCP

Per Claude Desktop la documentazione di Carbon Forge dice: "add an MCP server entry pointing at the instance URL with the token in the Authorization header." (aggiungete una voce di server MCP che punti all'URL dell'istanza con il token nell'intestazione Authorization.) Per i plugin degli IDE: "point the plugin at the same MCP endpoint; Streamable HTTP works over plain HTTPS." (puntate il plugin allo stesso endpoint MCP; Streamable HTTP funziona su semplice HTTPS.) Qualunque sia il formato del file del client, questi sono i tre valori da inserire:

Endpoint:  https://carbonforge.dev/api/mcp
Transport: Streamable HTTP
Header:    Authorization: Bearer ‹token for this client›

Passo 6. Verificate ogni client con cortex.ground

Chiedete a ogni client di chiamare cortex.ground. Restituisce "the calling identity, what the bearer can do, what is reachable" (l'identità chiamante, cosa può fare il bearer, cosa è raggiungibile) (cortex.ground). Confrontate le risposte: ogni client deve mostrare lo stesso workspace e le capacità che il suo ambito consente. Un client con un token sbagliato viene rifiutato; la documentazione dice che un token non valido è "refused outright rather than quietly treated as anonymous" (rifiutato subito invece di essere trattato in silenzio come anonimo).

Passo 7. Indicate il workspace in ogni chiamata

Ogni token ricorda il proprio workspace corrente, quindi "every agent has its own active workspace and they do not collide" (ogni agente ha il proprio workspace attivo e non si scontrano) (MCP token scopes). Significa anche che due client possono puntare in silenzio a workspace diversi. Dite a ogni agente di passare workspace in ogni chiamata: gli strumenti lo accettano e non sposta mai il puntatore.

Passo 8. Date a ogni agente che scrive la propria lane

Le note condivise sono pagine; il codice condiviso è dove i client si scontrano. In Carbon Forge un agente apre una lane invece di clonare: "A lane costs nothing to open and holds no copy, so one per task, or one per agent, is the expected use" (aprire una lane non costa nulla e non contiene copie, quindi una per compito, o una per agente, è l'uso previsto) (Working in lanes). Carbon Forge non fonde mai il testo da solo; una patch che non si applica più torna come conflitto nominato, e un'integrazione è un solo changeset, tutto o niente. L'agente di Cursor e Codex possono lavorare sullo stesso trunk senza un merge silenzioso tra loro.

Cosa la documentazione lascia senza risposta

Nessuna configurazione specifica per client. La documentazione di Carbon Forge nomina Claude Desktop e i plugin degli IDE in una frase ciascuno e non dà nessun file per Cursor o Codex; i frammenti qui sopra vengono dalla documentazione di Cursor e di Codex.
L'endpoint per un'istanza su un host proprio o un dominio personalizzato non è indicato; https://carbonforge.dev/api/mcp è quello che nomina la documentazione.
How MCP works mostra una chiamata curl a /mcp, mentre la pagina sull'accesso anonimo usa /api/mcp.
Se i token scadano da soli non è detto; come revocarne uno sì.
Il login OAuth per i client MCP non è menzionato; il metodo documentato è un bearer token.

Collegare Cursor, Codex e qualsiasi client MCP a un solo workspace Carbon Forge