Claude Desktop — Setup MCP Vault (remote)

O vault expõe um MCP gateway em https://vault.kodama.solutions/api/mcp que agrega tools de várias fontes — notas do brain, Linear, GitHub, etc. Autenticação é OAuth 2.0 (descoberta automática + dynamic client registration). Sem clone local, sem npx, sem PAT colado no JSON.

Pra setup local-only via filesystem do clone, ver setup/claude-code (CLI).

Pré-requisitos

Claude Desktop atualizado — versões recentes suportam transporte Streamable HTTP nativo. Se a tua versão for antiga, ver seção fallback abaixo.
Conta admin no vault com permissão pra aprovar o client OAuth.

Passo 1 — Abre o config

Localização do claude_desktop_config.json por OS:

OS	Caminho
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Atalho na UI: Settings → Developer → Edit Config.

Passo 2 — Adiciona o server

Bloco mínimo:

{
  "mcpServers": {
    "vault": {
      "url": "https://vault.kodama.solutions/api/mcp"
    }
  }
}

Sem token no arquivo. Claude Desktop descobre o OAuth via WWW-Authenticate na primeira chamada e abre o navegador pra autorização.

Passo 3 — Reinicia o app

Claude Desktop só carrega MCPs no boot.

macOS: Cmd+Q (não a bolinha vermelha)
Windows: Bandeja do sistema → Quit
Linux: pkill -f Claude se necessário

Passo 4 — Autoriza

Abre uma conversa nova. O app vai:

Tentar conectar em /api/mcp → recebe 401 missing bearer token
Ler WWW-Authenticate: Bearer realm="vault-mcp", resource_metadata=...
Buscar /.well-known/oauth-protected-resource e /.well-known/oauth-authorization-server
Registrar dinamicamente um client (POST /api/oauth/register)
Abrir teu navegador no /api/oauth/authorize — loga e clica em Authorize
Trocar o code por access token + refresh token e armazenar localmente

Tokens ficam em:

macOS: ~/Library/Application Support/Claude/credentials/
Windows: %APPDATA%\Claude\credentials\
Linux: ~/.config/Claude/credentials/

Passo 5 — Verifica

Na conversa, pergunta:

lê brain/MOC.md e resume

Deve aparecer tool call tipo mcp__vault__read_note. Outras tools disponíveis (variam conforme servers conectados no gateway):

Vault native: read_note, write_note, list_notes, search_notes, semantic_search, list_projects, save_document, extract_images...

⚠️ write_note path é relativo a brain/ — não prefixa. path: "projects/x.md"
grava em brain/projects/x.md. Passar path: "brain/projects/x.md" (com o prefixo)
grava em brain/brain/projects/x.md — duplicado e fora do lugar que ninguém lê.
Incidente 2026-06-30/07-01: 18 notas (specs de subagents + docs de projeto) foram
parar lá por esse erro, incluindo um launch-qa-checklist.md referenciado por um
subagent que ficou "sumido" até a correção. Depois de escrever, confere com
list_notes ou ls brain/<pasta>/ que a nota caiu no lugar certo.

Linear (se connected: true): list_issues, save_issue, list_comments, save_comment...
GitHub (se connected: true): repos, issues, PRs

Lista completa do estado atual:

curl -sS https://vault.kodama.solutions/api/mcp

Retorna JSON com servers[].connected + tool_count.

Fallback via `mcp-remote`

Se a tua versão do Claude Desktop não suporta "url" direto (algo antes de mid-2025), usa o bridge stdio mcp-remote:

{
  "mcpServers": {
    "vault": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://vault.kodama.solutions/api/mcp"]
    }
  }
}

mcp-remote faz o OAuth dance e expõe o transport como stdio. Mesma UX, custo de spawning um node a cada boot do app.

Troubleshooting

App não abre o navegador — confere se o browser default está setado no OS. Ou força reset: apaga credentials/ e reinicia.
"OAuth callback failed" — geralmente firewall/proxy bloqueando o redirect localhost. Tenta numa rede limpa.
Tools do Linear/GitHub não aparecem — esses sub-servers no gateway precisam de env (LINEAR_API_KEY, GITHUB_PERSONAL_ACCESS_TOKEN). Configurados em https://vault.kodama.solutions/settings (lado do servidor, não no client).
"missing bearer token" repetido — token expirou e refresh falhou. Apaga credentials/<vault> e re-autoriza.
Cloudflare 403/503 — vault às vezes pega challenge. Aguarda 30s ou troca de IP/VPN.

Por que remote em vez de filesystem

Multi-fonte num server só — notas + Linear + GitHub no mesmo endpoint
Sem clone local — não precisa git pull antes de editar; vault já é a fonte de verdade
Auth por OAuth, não PAT no JSON — revogável por usuário, sem segredo em texto plano
Sync automático — write_note grava direto no remote, sem passar pelo clone local (evita conflitos com Stop hook do Claude Code rodando em paralelo)

Trade-off: depende da rede e do uptime do vault. Pra trabalho offline, setup/claude-code com filesystem MCP no clone local ainda funciona.

Ver também

setup/index — overview
setup/claude-code — Claude Code CLI (filesystem local)
setup/vscode-copilot — VS Code Copilot