Alcance Docs

Instalação no Claude Desktop

Este guia descreve como conectar o Claude Desktop ao servidor MCP da Alcance Contabilidade usando um custom connector com autenticação Bearer.

Pré-requisito

Requer Claude Desktop com Developer Mode habilitado. Em planos Free, o suporte a connectors customizados pode estar limitado — recomendamos planos Pro, Team ou Enterprise.

Pré-requisitos

  • Claude Desktop instalado (macOS ou Windows).
  • Um valor válido de MCP_BEARER_TOKEN (peça ao time de TI da Alcance ou veja a seção de tokens no troubleshooting).
  • Acesso à URL pública https://mcp-alcancecontabilidade.vercel.app/api/mcp (a partir da sua rede).

Passo a passo

1. Abrir as configurações de desenvolvedor

  1. Abra o Claude Desktop.
  2. Clique no avatar/menu no canto inferior esquerdo → Settings.
  3. No menu lateral, vá em Developer.
  4. Se for a primeira vez, ative a opção Enable Developer Mode.

2. Adicionar o conector customizado

  1. Ainda em Developer, clique em Add custom connector.
  2. Preencha o formulário:
CampoValor
NameAlcance Contabilidade
DescriptionMCP da WebApiAlcance — clientes, certidões e lembretes.
URLhttps://mcp-alcancecontabilidade.vercel.app/api/mcp
TransportStreamable HTTP (padrão)
  1. Em Authentication, escolha Manual.
  2. No campo de header, adicione:
Authorization: Bearer COLE_AQUI_SEU_MCP_BEARER_TOKEN
  1. Clique em Save / Connect.

Verificação visual

O painel de Authentication mostrará um único campo de header já preenchido com Authorization. Você cola o valor Bearer <token> no campo de valor. O Claude indica "Connected" com um ponto verde ao lado do nome do connector quando a primeira chamada tools/list retorna 200.

3. Testar a conexão

Crie um novo chat e envie:

Liste 5 clientes da Alcance Contabilidade.

O Claude deve:

  1. Reconhecer que possui o tool buscar_cliente.
  2. Pedir confirmação para chamar a ferramenta (na primeira execução).
  3. Retornar a lista formatada.

Outros prompts úteis para validação inicial:

Quais certidões estão vencidas hoje?
Quais lembretes vencem essa semana?
Qual é o status da task abc-123-xyz?

Troubleshooting rápido

SintomaO que fazer
401 UnauthorizedToken inválido ou faltando. Confirme o cabeçalho Authorization: Bearer … e o valor exato.
Connector aparece desconectadoClique em Reconnect. Se persistir, verifique se a URL está acessível pelo navegador (deve retornar 405/406 — isso é esperado em GET direto).
Tool não aparece na listaForce um refresh do connector (desligar/ligar). O Claude cacheia o resultado de tools/list por sessão.
Timeout em chamadas writeAumente a paciência: writes que disparam Celery podem demorar. Use depois consultar_status_task.

Mais detalhes em Troubleshooting.

Próximos passos