Anche in: English, Español, Português, 日本語, Deutsch, Français, 한국어, 简体中文, हिन्दी · Tutte le guide in italiano
Trasparenza: sviluppiamo Carbon Forge in 100monkeys.ai, quindi leggete questo testo come il resoconto di chi lo costruisce. L'ha scritto in bozza uno dei nostri agenti di IA a partire dalla documentazione pubblica su carbonforge.dev/docs (in inglese) e l'azienda l'ha rivisto; questa edizione italiana è una traduzione della guida originale in inglese. I passi di Carbon Forge citano la documentazione; il comando di Claude Code viene dall'aiuto di Claude Code stesso, claude mcp add --help. Dove la documentazione lascia aperta una domanda, lo dice l'ultima sezione.
Perché collegarli
Un agente di programmazione dimentica tra una sessione e l'altra, a meno che le sue note non stiano in un posto che può rileggere. Carbon Forge è quel posto, condiviso con le persone del progetto. La documentazione chiama MCP "a primary product surface, co-equal with the human editor, against the same atoms, pages, links, and embeddings" (una superficie primaria del prodotto, alla pari con l'editor umano, sugli stessi atomi, pagine, link ed embedding; A shared cortex for LLMs). La pagina di un agente è una pagina che una persona può aprire, correggere e collegare.
Passo 1. Provare l'endpoint in sola lettura senza token
Prima di registrarvi, collegatevi ai contenuti pubblici. Da Reading a public cortex without an account: "Add the instance's MCP endpoint to your client with no Authorization header. For this instance that is https://carbonforge.dev/api/mcp over Streamable HTTP. With Claude Code:" (Aggiungete al vostro client l'endpoint MCP dell'istanza senza header Authorization; per questa istanza è quell'indirizzo, via Streamable HTTP. Con Claude Code:)
claude mcp add --transport http cortex-public https://carbonforge.dev/api/mcpOttenete ventidue strumenti in sola lettura, con un limite di richieste per indirizzo IP. Chiedete a Claude Code di leggere la pagina home nel workspace docs; senza token non c'è un workspace corrente, quindi ogni chiamata indica workspace. Rimuovete questa voce con claude mcp remove cortex-public prima di aggiungere quella autenticata, così l'agente non legge due superfici.
Passo 2. Accedere e scegliere il workspace
Accedete su carbonforge.dev/login con un link via e-mail o con il pulsante 100monkeys; non ci sono password. I workspace pubblici sono gratuiti, e ogni account include un workspace privato gratuito (prezzi). Decidete quale workspace l'agente userà come memoria. Uno privato tiene le note tra i membri.
Passo 3. Creare un token con la portata più stretta che basti
Da MCP tokens: aprite le impostazioni e scegliete API tokens; scegliete il workspace e un tetto di ruolo (viewer, editor o admin); scegliete un ambito di strumenti; date al token il nome dell'agente; copiate il segreto, che "is shown once, then only the prefix." (viene mostrato una volta, poi solo il prefisso.)
Per la memoria condivisa, Basic LLM memory permette all'agente di "read and write pages, atoms and tags, and run search, with basic graph reads" (leggere e scrivere pagine, atomi e tag ed eseguire ricerche, con letture di base del grafo), che la documentazione chiama "the minimum for an LLM that uses Carbon Forge as its memory." (il minimo per un LLM che usa Carbon Forge come memoria.) Per un agente che si limita a ricordare, Read-only memory non scrive nulla. Per il lavoro sul codice, SCM agent aggiunge lane, alberi e landing (MCP token scopes). Uno strumento fuori dall'ambito "answers exactly as a tool that does not exist." (risponde esattamente come uno strumento che non esiste.)
Passo 4. Aggiungere il server a Claude Code con il token
La documentazione dice di puntare il client all'endpoint "with the token in the Authorization header" (con il token nell'header Authorization). Claude Code imposta gli header con --header:
claude mcp add --transport http carbon-forge https://carbonforge.dev/api/mcp \
--header "Authorization: Bearer ‹your token›"Se mettete il token in una variabile d'ambiente e scrivete invece $CARBON_FORGE_TOKEN, la shell la espande prima che Claude Code la veda, quindi il segreto finisce comunque nella configurazione di Claude Code. Trattate quella configurazione come un segreto in entrambi i casi, e tenete il server nell'ambito predefinito local o nell'ambito user, non in un file che committate.
Passo 5. Lasciare che l'agente si orienti
Avviate una sessione e chiedete a Claude Code di chiamare cortex.ground. La documentazione ne fa la prima chiamata: "Returns the per-instance README, the calling identity, what the bearer can do, what is reachable, and helper-service health" (restituisce il README dell'istanza, l'identità chiamante, cosa può fare il titolare, cosa è raggiungibile e lo stato dei servizi di supporto; cortex.ground). La chiamata grezza è:
{ "jsonrpc": "2.0", "id": 1,
"method": "tools/call",
"params": { "name": "cortex.ground" } }Il server consegna lo stesso contenuto anche nell'handshake initialize e alla prima chiamata a strumento di una sessione, quindi un agente che salta questo passo è comunque orientato. Leggete il blocco capabilities per confermare che il token può scrivere.
Passo 6. Scrivere memoria, poi citarla
Chiedete all'agente di registrare ciò che ha imparato come una pagina, per esempio una decisione e il suo motivo, e di leggere quella pagina all'inizio della sessione successiva. Due proprietà ne fanno una memoria e non una cache. Ogni salvataggio scrive una nuova versione e niente riscrive una versione precedente, così potete leggere ciò che l'agente ha scritto la settimana scorsa. E "every entity-returning tool decorates the result with a clickable permalink so an LLM can hand a working URL back to its human" (ogni strumento che restituisce un'entità aggiunge al risultato un permalink cliccabile, così un LLM può restituire alla sua persona un URL funzionante; How MCP works): chiedete all'agente di citare il permalink di ogni pagina su cui si è basato, e controllateli.
Anche il codice sta nello stesso registro. Un agente apre una lane invece di clonare, e un landing è un unico changeset, scritto in una sola transazione o per niente (Working in lanes).
Passo 7. Osservare l'audit log e revocare alla fine
"Every tool call lands in the audit log under the token identity." (Ogni chiamata a strumento finisce nell'audit log sotto l'identità del token.) Quando l'agente non ha più bisogno dell'accesso, o il token trapela, revocatelo dalle impostazioni; "in-flight calls fail on the next request" (le chiamate in corso falliscono alla richiesta successiva; MCP tokens).
Cosa la documentazione lascia senza risposta
- L'endpoint per un'istanza su un host proprio. La pagina sull'accesso anonimo indica
https://carbonforge.dev/api/mcp"for this instance" (per questa istanza); non dice quale URL usare per un'istanza su un proprio sottodominio o dominio personalizzato. - Due percorsi. La stessa pagina usa
/api/mcp; l'esempio curl in How MCP works invia a/mcp. Noi usiamo/api/mcp. - La durata del token. La documentazione descrive la revoca ma non dice se un token scade da solo.
- La configurazione specifica del client. La documentazione non dà alcun comando per Claude Code; quello qui sopra è la sintassi documentata di Claude Code per un header.