Também em: English, Español, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todos os guias em português
Aviso: desenvolvemos o Carbon Forge na 100monkeys.ai, então leia isto como o relato de quem o fabrica. Este guia foi redigido por um dos nossos agentes de IA a partir da documentação pública em carbonforge.dev/docs (em inglês) e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. Os passos do Carbon Forge citam a documentação; o comando do Claude Code vem da ajuda do próprio Claude Code, claude mcp add --help. Onde a documentação deixa uma pergunta em aberto, a última seção diz isso.
Por que conectar os dois
Um agente de programação esquece tudo entre sessões, a menos que suas anotações fiquem num lugar que ele possa ler de novo. O Carbon Forge é esse lugar, compartilhado com as pessoas do projeto. A documentação chama o MCP de "a primary product surface, co-equal with the human editor, against the same atoms, pages, links, and embeddings" (uma superfície principal do produto, no mesmo nível do editor humano; A shared cortex for LLMs). A página de um agente é uma página que uma pessoa pode abrir, corrigir e linkar.
Passo 1. Teste o endpoint somente leitura sem token
Antes de se cadastrar, conecte-se ao conteúdo público. Segundo 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:" (adicione o endpoint MCP da instância ao seu cliente sem cabeçalho Authorization; com o Claude Code:)
claude mcp add --transport http cortex-public https://carbonforge.dev/api/mcpVocê ganha vinte e duas ferramentas somente leitura, com limite de requisições por endereço IP. Peça ao Claude Code para ler a página home do workspace docs; sem token não existe workspace atual, então toda chamada informa workspace. Remova esta entrada com claude mcp remove cortex-public antes de adicionar a autenticada, para o agente não ler duas superfícies.
Passo 2. Entre e escolha o workspace
Entre em carbonforge.dev/login com um link por e-mail ou com o botão da 100monkeys; não há senhas. Workspaces públicos são gratuitos, e toda conta inclui um workspace privado gratuito (preços). Decida qual workspace o agente vai usar como memória. Um privado mantém as anotações só para os membros.
Passo 3. Crie um token com o escopo mais restrito que atenda
Segundo MCP tokens: abra as configurações e escolha API tokens; selecione o workspace e um papel máximo (viewer, editor ou admin); escolha um escopo de ferramentas; dê ao token o nome do agente; copie o segredo, que "is shown once, then only the prefix" (aparece uma vez e depois só o prefixo).
Para memória compartilhada, Basic LLM memory permite ao agente "read and write pages, atoms and tags, and run search, with basic graph reads" (ler e escrever páginas, átomos e tags, e fazer buscas), o que a documentação chama de "the minimum for an LLM that uses Carbon Forge as its memory" (o mínimo para um LLM que usa o Carbon Forge como memória). Para um agente que só consulta, Read-only memory não escreve nada. Para trabalho com código, SCM agent acrescenta lanes, árvores e integração (MCP token scopes). Uma ferramenta fora do escopo "answers exactly as a tool that does not exist" (responde exatamente como uma ferramenta que não existe).
Passo 4. Adicione o servidor ao Claude Code com o token
A documentação diz para apontar o cliente para o endpoint "with the token in the Authorization header" (com o token no cabeçalho Authorization). O Claude Code define cabeçalhos com --header:
claude mcp add --transport http carbon-forge https://carbonforge.dev/api/mcp \
--header "Authorization: Bearer ‹your token›"Se você colocar o token numa variável de ambiente e escrever $CARBON_FORGE_TOKEN no lugar, o shell expande a variável antes de o Claude Code vê-la, então o segredo fica salvo na configuração do Claude Code do mesmo jeito. Trate essa configuração como segredo nos dois casos e mantenha o servidor no escopo padrão local ou no escopo user, não num arquivo que você commita.
Passo 5. Deixe o agente se orientar
Inicie uma sessão e peça ao Claude Code para chamar cortex.ground. A documentação coloca essa como a primeira chamada: "Returns the per-instance README, the calling identity, what the bearer can do, what is reachable, and helper-service health" (retorna o README da instância, a identidade de quem chama, o que o portador pode fazer, o que está acessível e a saúde dos serviços auxiliares; cortex.ground). A chamada bruta é:
{ "jsonrpc": "2.0", "id": 1,
"method": "tools/call",
"params": { "name": "cortex.ground" } }O servidor também entrega essas mesmas informações no handshake initialize e na primeira chamada de ferramenta de uma sessão, então um agente que pula este passo fica orientado mesmo assim. Leia o bloco capabilities para confirmar que o token pode escrever.
Passo 6. Escreva memória e depois cite
Peça ao agente para registrar o que aprendeu como uma página, por exemplo uma decisão e seu motivo, e para ler essa página no início da próxima sessão. Duas propriedades fazem disso uma memória, e não um cache. Cada salvamento grava uma nova versão e nada reescreve uma anterior, então você pode ler o que o agente escreveu na semana passada. E "every entity-returning tool decorates the result with a clickable permalink so an LLM can hand a working URL back to its human" (toda ferramenta que retorna uma entidade inclui um permalink clicável; How MCP works): peça ao agente para citar o permalink de cada página em que se apoiou, e confira.
O código fica no mesmo registro. Um agente abre uma lane em vez de clonar, e uma integração é um único changeset, gravado numa transação ou não gravado (Working in lanes).
Passo 7. Acompanhe o log de auditoria e revogue ao terminar
"Every tool call lands in the audit log under the token identity." (Toda chamada de ferramenta entra no log de auditoria com a identidade do token). Quando o agente não precisar mais de acesso, ou se o token vazar, revogue-o nas configurações; "in-flight calls fail on the next request" (chamadas em andamento falham na próxima requisição; MCP tokens).
O que a documentação deixa sem resposta
- O endpoint de uma instância no seu próprio host. A página de acesso anônimo cita
https://carbonforge.dev/api/mcp"for this instance"; não diz qual URL usar para uma instância no próprio subdomínio ou num domínio personalizado. - Dois caminhos. A mesma página usa
/api/mcp; o exemplo com curl em How MCP works envia para/mcp. Usamos/api/mcp. - Validade do token. A documentação descreve como revogar um token, mas não diz se ele expira sozinho.
- Configuração por cliente. A documentação não traz um comando para o Claude Code; o de cima é a sintaxe documentada do Claude Code para um cabeçalho.