Voltar à Documentação

Conectando o Sutram ao Claude

Conecte o Sutram ao Claude (e a outros assistentes de IA compatíveis com MCP) para consultar, resumir e editar o conteúdo dos seus projetos em linguagem natural.

Visão geral — dois caminhos

Você usa Use este caminho
Claude.ai (web) ou Claude Desktop com Conectores Personalizados Conector OAuth — um clique, sem chaves de API
Claude Code (CLI), Cursor ou versões antigas do Claude Desktop Ponte por chave de API — um arquivo de configuração com as duas chaves

Os dois caminhos falam com o mesmo servidor MCP do Sutram e expõem as mesmas ferramentas. Escolha o que o seu cliente suporta melhor. A referência completa das ferramentas está no Guia do Sutram MCP Server.

Requisito de plano: O acesso MCP requer uma assinatura Sutram no plano Pro ou superior. O plano Basic não inclui MCP.

Caminho A — Conector OAuth (recomendado)

Para Claude.ai (web) e Claude Desktop com suporte a Conectores Personalizados. Não é preciso copiar chaves — a autorização é feita por OAuth.

1. Abra o painel de Conectores no Claude

  1. Abra Configurações (ícone de engrenagem) → Conectores
  2. Clique em Adicionar conector personalizado

2. Informe a URL do Sutram

  • Nome: Sutram (ou o rótulo que preferir)
  • URL:
https://app.sutram.io/mcp/v2

Clique em Adicionar.

3. Conecte e autorize

Clique em Conectar. O Claude abre uma janela do navegador em https://app.sutram.io/mcp/v2/oauth/authorize.

  • Se você já estiver logado no Sutram, vai direto para a tela de consentimento.
  • Caso contrário, faça login no Sutram primeiro; a tela de consentimento aparece em seguida.

A tela de consentimento pede para você escolher o projeto que o conector vai acessar. O token OAuth fica restrito a esse único projeto — escolha com atenção.

Clique em Autorizar. Você volta ao Claude com o conector marcado como conectado.

4. Libere a rede (uma vez, até a listagem no diretório)

O Claude.ai mantém uma allowlist de rede de saída. O tráfego MCP para app.sutram.io é liberado por padrão, mas os downloads de arquivo vêm de uma CDN e os uploads vão direto para o S3 — ambos precisam de autorização explícita, uma única vez:

  1. Configurações → Capabilities (o nome da seção varia conforme a versão do Claude) → procure a allowlist de rede de saída
  2. Em domínios permitidos, adicione os três:
    • app.sutram.io — endpoint MCP, OAuth e descoberta
    • files.sutram.io — downloads de arquivo (borda CloudFront)
    • *.s3.amazonaws.com — uploads diretos (URL pré-assinada)

Quando o Sutram estiver listado no Anthropic Connectors Directory, esses três domínios são declarados na listagem e os clientes os autorizam automaticamente.

5. (Opcional) Aplique o Preset do Assistente Sutram

Sem o preset, o Claude funciona — mas pode, de vez em quando, pedir para você "anexar um arquivo" ou "conectar uma pasta" quando você quer dizer um documento do Sutram, porque não sabe qual contexto assumir.

Para deixar o Claude ciente do Sutram por padrão, copie o System Prompt do Preset do Assistente Sutram e cole nas Instruções Personalizadas do seu projeto no Claude (Personalização / System Prompt do projeto — o nome varia por cliente). Depois disso, pedidos como "Resuma meu último exame de cardiologia" vão direto ao conector do Sutram, sem pedir upload.

6. Teste com um prompt inicial

Abra uma nova conversa e peça:

Me mostre um panorama do meu projeto e do que há nele.

O Claude chama sutram_project_info e sutram_get_folder em sequência e devolve um resumo estruturado da raiz do seu projeto.

Caminho B — Ponte por chave de API (Claude Code, Cursor, Desktop antigo)

Use quando o seu cliente ainda não suporta Conectores Personalizados (Claude Code CLI, Cursor, versões antigas do Claude Desktop ou desenvolvimento local contra uma instância não pública do Sutram).

1. Crie sua chave de API pessoal

Vá em Configurações → Integrações → Claude e clique em Gerar chave de usuário.

Sua chave pessoal se parece com:

sk_user_…

Copie na hora — ela não pode ser recuperada depois. Se perder, revogue a antiga e gere uma nova na mesma tela.

2. Obtenha a chave do projeto

O proprietário do projeto precisa primeiro habilitar o acesso MCP:

Configurações do Projeto → Integrações → ative Habilitar acesso MCP.

Depois disso, qualquer membro do projeto (proprietário, administrador ou membro) pode copiar a chave do projeto na mesma tela:

sk_proj_…

3. Configure seu cliente

O mesmo bloco JSON funciona nos três clientes — só muda o local do arquivo. A ponte usa o pacote mcp-remote, e as duas chaves vão juntas num único header Authorization:

{
  "mcpServers": {
    "sutram": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.sutram.io/mcp/v2",
        "--header",
        "Authorization: Bearer dualkey:sk_proj_...:sk_user_..."
      ]
    }
  }
}

Substitua sk_proj_... e sk_user_... pelas suas chaves reais.

O header Authorization deve estar em uma única linha — o JSON não permite quebras de linha dentro de strings. A chave de usuário (sk_user_…) identifica você e é a mesma em todos os projetos; a chave do projeto (sk_proj_…) muda por projeto. Requer Node.js (o npx baixa o mcp-remote no primeiro uso).

Claude Code (CLI)

Crie o JSON acima como .claude/mcp.json na pasta do seu workspace. Inicie o Claude Code a partir dessa pasta; as ferramentas do Sutram ficam restritas a esse workspace.

Cursor

Crie o JSON acima como .cursor/mcp.json na pasta do projeto.

Claude Desktop (versões antigas)

Edite o arquivo de configuração global e adicione o bloco mcpServers ao lado das entradas existentes:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Reinicie o Claude Desktop após salvar.

4. Teste com um prompt

Me mostre um panorama do meu projeto Sutram.

Clientes de ponte não impõem allowlist de rede, então os downloads de arquivo funcionam sem configuração extra.

Segurança das chaves

  • As chaves são independentes: revogar uma chave de usuário não afeta outros usuários. Revogar a chave de projeto desabilita o acesso remoto para todos naquele projeto.
  • Uma chave de projeto por projeto: apenas uma fica ativa por vez; regenerá-la invalida a anterior.
  • Chaves nunca são armazenadas em texto puro: chaves de projeto são criptografadas; chaves de usuário são hasheadas — não podem ser recuperadas após a criação.
  • Apenas HTTPS: todas as conexões usam HTTPS criptografado.

Revogando acesso

  • Sua chave pessoal: Configurações → Integrações → Claude → revogar a chave.
  • Acesso MCP do projeto (apenas proprietário): Configurações do Projeto → Integrações → desabilitar o acesso MCP.

Solução de problemas de conexão

Sintoma Causa provável Correção
"Não foi possível alcançar o servidor MCP" no primeiro connect O conector tentou a descoberta OAuth e foi bloqueado pela allowlist Confirme que app.sutram.io está acessível (curl -I https://app.sutram.io/mcp/v2 deve responder). Se sim, revise o Caminho A, passo 4.
Tela de consentimento aparece, mas Autorizar retorna 500 Erro no servidor ao persistir o consentimento Instabilidade. Contate support@sutram.io com o horário.
Conector conectado, mas chamadas retornam 401 Token de acesso expirou (TTL de 1 hora) Repita o prompt — o Claude renova automaticamente pelo refresh token. Se falhar de novo, clique em Reconectar.
Claude responde "não tenho acesso a nenhuma pasta no seu computador" Interpretou um prompt genérico como pedido de sistema de arquivos Seja explícito ("…no Sutram") ou aplique o Preset do Assistente (Caminho A, passo 5).
Leitura de arquivo falha com "rede bloqueada" app.sutram.io está liberado, mas files.sutram.io não Adicione files.sutram.io à allowlist (Caminho A, passo 4).
Fluxo OAuth volta para a tela de login Navegador bloqueando cookies de terceiros no popup de consentimento Use Firefox ou Chrome, ou desative temporariamente a proteção estrita de rastreamento no Safari.
Ferramentas não aparecem no Claude Code / Cursor Ponte mal configurada Confirme que o Node.js (npx) está instalado e que o arquivo (.claude/mcp.json ou .cursor/mcp.json) está na pasta a partir da qual você inicia o cliente.

Recursos

  • Guia do Sutram MCP Server — a referência completa das ferramentas disponíveis
  • Preset do Assistente Sutram — System Prompt e prompts iniciais para deixar o Claude ciente do Sutram por padrão
  • Suporte: support@sutram.io

Versão do Documento: 1.0 Última Atualização: Julho de 2026 Autor: Equipe de Desenvolvimento Sutram

Voltar à Documentação