Documentação · Conector

Conector Claude

Conectar a OSPA ao Claude permite consultar e operar dados da plataforma direto do chat — sem trocar de ambiente.

Como funciona

O conector é um servidor MCP (Model Context Protocol) público autenticado por OAuth 2.1. Ao conectar, o Claude recebe um token escopado ao workspace selecionado, com o mesmo perfil de acesso que o usuário já tem na web.

Operações são executadas em nome do usuário autenticado e ficam registradas no log de auditoria com a origem identificada — separando ações vindas do conector de ações da web.

Pré-requisitos

Conta OSPA ativa em pelo menos um workspace.
Role do workspace define o que o conector pode fazer: viewer (somente leitura), editor (leitura e escrita), admin (acesso completo no escopo da v1).
Cliente compatível com MCP remoto: Claude no navegador (claude.ai) ou Claude Desktop.

Conectar pelo Claude (web)

Abrir o Claude e ir em Settings → Connectors.
Adicionar conector personalizado apontando para a URL do servidor MCP da OSPA: https://app.ospa.com.br/api/mcp/mcp.
O Claude inicia o fluxo OAuth. Quando aberta a tela de autorização da OSPA, fazer login (se ainda não estiver) e escolher o workspace que o Claude vai operar.
Revisar as permissões solicitadas e clicar em Autorizar.
Após autorização, o Claude já pode chamar as operações disponíveis para o perfil.

Conectar pelo Claude Desktop

O Claude Desktop também suporta conectores MCP remotos. Para conta pessoal sem OAuth dinâmico, é possível usar um Personal Access Token gerado em Settings → Integrações.

{
  "mcpServers": {
    "ospa": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://app.ospa.com.br/api/mcp/mcp",
        "--header", "Authorization: Bearer pfm_<seu-token>"
      ]
    }
  }
}

Personal Access Tokens são para uso individual e não trafegam pelo fluxo OAuth público. Para integrações multiusuário, prefira o conector OAuth via claude.ai.

Escopo da v1

v1 — Deal Management para Incorporadora

A primeira versão do conector cobre operações sobre projetos e deals em workspaces tipo incorporadora ou originador. Investidor/gestor e time interno entram em versões seguintes, conforme o roadmap abaixo.

Incorporadora — disponível agora

Workspace tipo incorporadora ou originador. Role viewer tem acesso a leitura; editor e admin têm escrita.

· Listar e consultar projetos do workspace
· Buscar projetos por nome ou endereço
· Criar projetos e atualizar informações
· Atualizar custos de obra e indiretos
· Listar e consultar deals da incorporadora

Próximas versões — não disponível ainda

· Investidor/Gestor: oportunidades disponíveis no marketplace, deals compartilhados, status das teses.
· Time interno OSPA: escopo operacional sobre deals, incorporadoras, investidores e funil.
· Operações específicas: status de captação, viabilidade financeira detalhada, exposição de deal ao marketplace, aprovação de operações.
· Fora de roadmap nesta v1: Onboarding/KYC, Cobrança e Backoffice.

Exemplos de uso

Prompts que demonstram o que perguntar ao Claude depois de conectar. Cada exemplo aciona uma ou mais tools — o Claude escolhe e combina conforme a intenção.

Consulta de portfólio

"Liste meus projetos ativos no workspace. Para cada um, me diga o VGV total e o status atual."

Tools acionadas: list_projects

Análise financeira de um projeto

"Mostre o cashflow consolidado, IRR e exposição de dívida do projeto Residencial Bela Vista."

Tools acionadas: search_projects, get_project

Operações no funil de deals

"Quais deals do meu workspace estão em status marketplace? Me dá um resumo por deal — valor pedido, tipo e quanto já foi captado."

Tools acionadas: list_deals, get_deal

Atualização de informações

"Atualize o endereço do projeto Bela Vista para 'Avenida Ipiranga, 1500 — Porto Alegre/RS' e marque o status como 'em obra'."

Tools acionadas: search_projects, update_project_info

Busca por critério geográfico

"Procure todos os projetos do meu workspace que tenham endereço em Porto Alegre."

Tools acionadas: search_projects

Escopos OAuth

As permissões são granulares e exibidas na tela de autorização antes de o usuário consentir.

projects:read — Ler projetos e dados financeiros.
projects:write — Criar e atualizar projetos e custos.
deals:read — Ler deals do workspace.
deals:write — Criar e atualizar deals.

Tokens de acesso expiram em 1 hora; tokens de refresh em 30 dias e são rotacionados a cada uso.

Confirmação de ações sensíveis

Operações que alteram estado relevante — como aprovar um deal, mudar status de captação ou expor uma oportunidade ao marketplace — exigem duas chamadas: uma de preview, que devolve resumo e um token efêmero de operação, e uma de confirmação, que executa a ação com base nesse token. O padrão protege contra execuções sem revisão explícita do usuário no chat.

Como revogar

Acessar Settings → Integrações na OSPA. Na seção Aplicações conectadas, clicar em Revogar ao lado do conector. Todos os tokens daquele cliente para o workspace selecionado são invalidados imediatamente — o Claude perde o acesso e precisa passar pelo fluxo OAuth de novo se quiser reconectar.

Troubleshooting

Erros comuns que aparecem ao operar o conector e como resolver.

Conector aparece como “disconnected” sem motivo aparente

O token de acesso expirou (TTL de 1 hora). O Claude renova automaticamente via refresh token (TTL de 30 dias, rotacionado a cada uso). Se a desconexão persistir após o próximo prompt, revogar em Settings → Integrações e reconectar.

Erro “workspace selection is required” no consent

A tela de autorização exige seleção explícita de um workspace antes de aprovar. Selecionar o workspace correto na lista e clicar em Autorizar novamente.

Resposta vem com “[Resposta truncada — N caracteres adicionais omitidos.]”

O projeto excedeu o limite de ~25 mil tokens por resposta de tool. Em vez de pedir o projeto inteiro, pedir campos específicos (ex.: "mostre só os indicadores e o cashflow do projeto X") ou listar primeiro e depois pegar detalhes pontuais.

401 inesperado depois de já ter conectado

Token foi revogado — pelo usuário em Settings → Integrações, ou expirou e o refresh também já estava inválido. Reconectar pelo fluxo OAuth do Claude restaura o acesso.

Tool falha com “FORBIDDEN”

Faltam permissões. Causas comuns: (1) workspace selecionado tipo investidor — write tools não rodam aí; (2) role viewer tentando uma write tool (criar projeto, atualizar custos); (3) scope OAuth não inclui projects:write ou deals:write. Trocar workspace ou pedir role editor/admin.

DCR falhou ao adicionar o conector no Claude

Verificar se o domínio configurado no Claude tem HTTPS válido e se o endpoint /oauth/register responde com 201 — uma resposta HTML é sintoma de proxy/auth bloqueando rotas públicas. Se reproduzir, contatar suporte com o request ID.

Persistindo um erro não listado, abrir chamado em suporte@ospa.com.br com o prompt usado, a tool acionada (se conhecida) e o horário aproximado.

Segurança

Tokens hasheados: só o hash SHA-256 fica em banco; o valor cru é emitido uma única vez.
Auditoria: emissão, rotação, validação e revogação de tokens ficam registradas, com retenção de 90 dias.
Isolamento por workspace: toda operação filtra por workspace e respeita os controles de acesso existentes na plataforma — não há acesso cruzado entre tenants.
Limite de requisições: operações pelo conector compartilham o limite de chamadas AI por usuário, evitando abuso.
PKCE obrigatório: apenas o método S256 é aceito na autorização.

Fora do escopo desta versão

· Operações em lote — importação/exportação massiva via Claude
· Geração de gráficos, dashboards ou mapas
· Gerenciamento de permissões de outros usuários
· Webhooks empurrando notificações para sessão ativa no Claude
· Onboarding/KYC, Cobrança e Backoffice

Privacidade e termos

Ao autorizar o conector, o usuário concorda que os dados acessíveis pelo escopo selecionado podem ser processados pela aplicação cliente (a Anthropic, no caso do Claude), sob a política de privacidade dela. Conferir Política de Privacidade, Política específica do conector e Termos de Uso antes de conectar.