Configurar um servidor MCP deveria levar cinco minutos. Na prática, porém, a configuração vive cheia de caminhos absolutos — e cada máquina nova, cada colega com um usuário diferente, cada pasta movida de lugar significa editar tudo de novo. Pior ainda quando o mcp.json é versionado no repositório: o que funciona na sua máquina quebra na do time inteiro. Esta semana o Hermes ganha variáveis de contexto no estilo Cursor, para que os caminhos finalmente fiquem portáteis.

Ainda codificando caminhos na sua configuração MCP?

Configurar servidores MCP tem um problema recorrente e irritante: caminhos. /Users/neo/.cache/mcp, C:\Users\neo\projects\webapp — troque de máquina, troque de usuário, troque de diretório de projeto, e você edita tudo de novo. Pior: se sua equipe versiona a configuração MCP no repositório, os caminhos absolutos de cada um diferem e um mcp.json compartilhado se torna impossível de manter portátil.

Um recurso mesclado no main do Hermes Agent em 2026-08-08 resolve exatamente isso: as configurações de servidores MCP agora suportam interpolação de variáveis de contexto no estilo Cursor — ${userHome}, ${workspaceFolder}, ${workspaceFolderBasename}, ${pathSeparator} e ${/}. Duas consequências:

1. Um mcp.json que você escreveu para o Cursor migra para o Hermes com zero edições de caminho;
2. Caminhos nas configurações finalmente podem ser escritos em termos semânticos e relativos — portáteis entre máquinas e usuários.

As 5 variáveis de contexto

Variável (sensível a maiúsculas)	Resolve para
${userHome}	O diretório home do usuário atual (os.path.expanduser("~"))
${workspaceFolder}	A raiz do workspace da sessão (veja a cadeia de resolução abaixo)
${workspaceFolderBasename}	O basename de ${workspaceFolder} (último segmento do caminho)
${pathSeparator}	O separador de caminho do SO (os.sep — \ no Windows, / nos demais)
${/}	Atalho para ${pathSeparator}

⚠️ Maiúsculas importam: apenas essas cinco grafias exatas são reconhecidas. ${USERHOME} não é uma variável de contexto — ela cai na busca normal de variáveis de ambiente como qualquer outra referência ${...}.

Exemplos reais de configuração

As variáveis podem aparecer em qualquer posição de string de uma entrada de servidor: args, env, url, headers — em todas elas.

Exemplo 1: servidor filesystem apontando para o workspace atual

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]

Onde quer que você inicie o Hermes, o servidor filesystem aponta automaticamente para o workspace da sessão atual — sem IDs de sessão para lembrar, sem cd antes.

Exemplo 2: diretório de cache construído a partir de home + separador

mcp_servers:
  my-server:
    command: "node"
    args: ["server.js"]
    env:
      CACHE_DIR: "${userHome}${/}.cache${/}mcp"

${/} faz essa única configuração funcionar no Windows (\) e no macOS/Linux (/) ao mesmo tempo.

Exemplo 3: migrando direto do Cursor

O padrão mais comum no mcp.json do Cursor é a referência de segredo "${env:VAR}". O Hermes também suporta:

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${env:GITHUB_TOKEN}"

${env:GITHUB_TOKEN} e ${GITHUB_TOKEN} resolvem para a mesma variável; os valores são lidos do escopo de segredos do perfil ativo (com fallback para o ambiente do processo), então é só colocar o segredo em ~/.hermes/.env e pronto. Uma variável não definida mantém seu placeholder literal em vez de gerar erro.

Como o ${workspaceFolder} resolve (ordem de prioridade)

${workspaceFolder} não é simplesmente o diretório de início do processo — ele percorre uma cadeia de três níveis:

1. O cwd de terminal registrado da sessão: gravado a cada comando de terminal concluído e indexado pelo ID bruto da sessão — o cd de uma sessão nunca pode vazar para a resolução de outra;
2. Uma sobrescrita registrada de cwd de tarefa/sessão: o cwd que as sessões TUI / Desktop / ACP registram antes de qualquer ferramenta rodar;
3. Um $TERMINAL_CWD absoluto sem sentinela: o caminho do worktree definido para sessões hermes -w <worktree>.

Apenas quando não existe nenhuma âncora confiável é que ele recorre ao os.getcwd() do processo.

Na prática, isso significa: abra um projeto no app desktop, ou faça cd para um subdiretório na TUI, e ${workspaceFolder} acompanha o workspace real da sessão atual — não o diretório de onde você por acaso lançou.

Ordem de resolução: variáveis de contexto → variáveis de ambiente → literal

Para cada referência ${...}, a interpolação tenta, em ordem:

1. Correspondência exata com as 5 variáveis de contexto (prioridade máxima);
2. Busca em variáveis de ambiente (escopo de segredos do perfil → os.environ);
3. Caso contrário, o placeholder literal é mantido (ex.: "${NOT_EXIST}" permanece como está).

Ou seja, as variáveis de contexto não alteram nenhuma semântica existente de variáveis de ambiente — referências antigas como ${HOME} não são afetadas; você apenas ganhou cinco nomes de “primeira classe”.

Quando isso compensa

• Configurações compartilhadas em equipe: versionem mcp_servers no repositório e todo membro funciona após um clone — chega de pisar nos caminhos absolutos uns dos outros;
• Sincronização entre máquinas: desktop + laptop + CI compartilhando uma única configuração; ${userHome} e ${/} absorvem as diferenças de plataforma;
• Ferramentas vinculadas ao workspace: servidores que precisam rodar contra o projeto atual (filesystem, linters, busca de código) — ${workspaceFolder} acompanha a sessão automaticamente.

Para a referência completa de chaves de servidor MCP (tools.include/exclude, o nível trust, auth: oauth e mais), consulte nossa referência do comando hermes mcp. Para ver o panorama MCP mais amplo na versão mais recente, leia as notas de release do Herald v0.20.0. Novo no Hermes Agent? Comece pelo guia de instalação antes de experimentar.

Resumo: troque caminhos absolutos por ${userHome}, ${workspaceFolder} e ${/} na sua configuração MCP, e você ganha portabilidade mais o comportamento de “acompanhar o workspace atual” de graça — com configurações que interoperam com o ecossistema Cursor sem alterações.