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:

1. Tentar conectar em /api/mcp → recebe 401 missing bearer token
2. Ler WWW-Authenticate: Bearer realm="vault-mcp", resource_metadata=...
3. Buscar /.well-known/oauth-protected-resource e /.well-known/oauth-authorization-server
4. Registrar dinamicamente um client (POST /api/oauth/register)
5. Abrir teu navegador no /api/oauth/authorize — loga e clica em Authorize
6. 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...
• 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