MCP do Connect

Gerada do catálogo do próprio servidor MCP e dos metadados OAuth (Zoppy-crm/zoppy-connect@f1ae3a72be71).

O servidor MCP deixa uma IA consultar e operar o Connect da loja com as permissões de quem conectou: ver conectores, execuções, quarentena, escritas guardadas e agentes locais, e ligar, pausar, rodar agora, reprocessar ou confirmar a primeira escrita, sempre com prévia e confirmação. Segredos ficam fora da conversa.

Quem pode conectar

Usuários MASTER ou ADMIN da loja. Outros papéis não conseguem aprovar nenhuma permissão.
Lojas com o Connect liberado pelo time da Zoppy.
Com o termo do Connect aceito por um MASTER da loja (no primeiro acesso à tela).

A liberação e o termo são conferidos de novo em cada chamada: se o Connect for desligado para a loja, as ferramentas param de responder.

Endereço do servidor

Ambiente	Servidor MCP
Produção	`https://api-connect.zoppy.com.br/mcp`
Staging	`https://api-connect-staging.zoppy.com.br/mcp`

O transporte é Streamable HTTP (só POST) e o login é OAuth: não há chave de API para colar.

Conectar o cliente

Claude Code

claude mcp add --transport http zoppy-connect https://api-connect.zoppy.com.br/mcp

Use --scope user para ter o servidor em todos os projetos (o padrão, local, vale só para o projeto atual). Depois, dentro do Claude Code, rode /mcp e siga o login no navegador. Se o navegador não abrir sozinho, copie o endereço que o Claude Code mostra.

Claude (web e Claude Desktop)

No Claude, os servidores remotos entram como conectores personalizados da sua conta e valem também no Claude Desktop:

Abra Customize > Connectors.
Clique em + Add e em Add custom connector.
Dê um nome (por exemplo, Zoppy Connect), cole https://api-connect.zoppy.com.br/mcp e clique em Continue.
Confira a autenticação detectada (OAuth) e clique em Continue.
Em Authentication, escolha Sign in now, clique em Add e siga o login no navegador.

Em planos Team e Enterprise, quem adiciona é o dono da organização, em Organization settings > Connectors; cada pessoa depois clica em Connect em Customize > Connectors. O Claude Desktop não conecta servidores remotos escritos no claude_desktop_config.json: use o caminho acima.

Cursor

No ~/.cursor/mcp.json (todos os projetos) ou no .cursor/mcp.json do projeto:

{
  "mcpServers": {
    "zoppy-connect": {
      "url": "https://api-connect.zoppy.com.br/mcp"
    }
  }
}

O Cursor faz o login OAuth do servidor (código de autorização com PKCE). Funciona no aplicativo desktop, que recebe o retorno do login em localhost; o Cursor na web e os agentes do Cursor voltam para um endereço que o Connect não aceita.

Outros clientes MCP

Qualquer cliente com Streamable HTTP e OAuth do MCP funciona, se ele:

descobrir o servidor de autorização pelo WWW-Authenticate da primeira resposta 401 (metadados em https://api-connect.zoppy.com.br/.well-known/oauth-protected-resource/mcp);
se registrar sozinho (registro dinâmico, sem segredo de cliente) e usar PKCE S256;
receber o retorno do login em http na própria máquina (127.0.0.1 ou [::1] em qualquer porta, ou localhost), ou num destes endereços: https://claude.ai/api/mcp/auth_callback, https://claude.com/api/mcp/auth_callback.

Clientes que não fazem OAuth sozinhos, ou que só aceitam uma chave fixa, não conectam.

O cliente abre o navegador na Zoppy. Entre com a sua conta.
A tela de consentimento mostra o aplicativo, a loja, para onde o navegador volta e as permissões pedidas. Marque ao menos uma e autorize.
O cliente recebe um acesso que vale 1 hora(s) e se renova sozinho. A autorização vence em 30 dias: aí o cliente pede o login de novo, e o papel e a liberação são conferidos outra vez.

Permissões

Permissão	O que libera	Ferramentas
`connect:read`	Ver os conectores, as execuções (passos, erros e contadores), a quarentena e os agentes locais.	`list_connectors`, `list_runs`, `read_run`, `read_quarantine`, `list_held_writes`, `list_local_agents`
`connect:operate`	Ligar, pausar, rodar agora, reprocessar a quarentena e confirmar a primeira escrita guardada, sempre com prévia e confirmação.	`preview_operation`, `confirm_operation`

O cliente só vê as ferramentas das permissões que você marcou. Para ganhar outra, desconecte e conecte de novo marcando a que falta.

Prévia e confirmação

Nenhuma ferramenta muda nada num passo só:

preview_operation mostra o que vai acontecer (título e mudanças) e devolve um confirmationToken. Nada muda ainda.
O cliente mostra a prévia e pergunta se você concorda.
Só depois do seu sim ele chama confirm_operation com o token. O token vale uma vez, por 10 minutos, e só para quem pediu a prévia. Vencido ou já usado, responde connect.mcp_confirmation_invalid: peça a prévia de novo.

Operação	O que faz
`enable`	Liga o conector: ele passa a rodar no cron, com a versão publicada.
`pause`	Pausa o conector: o cron para até alguém ligar de novo.
`run_now`	Abre uma execução agora, fora do cron. O conector precisa estar ligado.
`reprocess_quarantine`	Reprocessa registros da quarentena: os de `itemIds`, ou os abertos mais novos.
`confirm_held_write`	Manda a primeira escrita guardada (`heldWriteId`) e libera as próximas naquele sistema.

As instruções que o servidor manda ao cliente ao conectar:

Zoppy Connect: os conectores que movem dados entre a loja na Zoppy e outros sistemas. Leia com list_connectors, list_runs, read_run, read_quarantine, list_held_writes e list_local_agents. Toda mudança é em dois passos: preview_operation mostra o que vai acontecer e devolve um confirmationToken; só chame confirm_operation depois que a pessoa concordar com a prévia. O token vale uma vez, por 10 minutos. Construir, publicar e editar o código dos conectores é só pela tela do Connect.

Ferramentas

`list_connectors`

O ponto de partida: devolve os ids que as outras ferramentas pedem. Pergunte “como estão os meus conectores?”.

Permissão connect:read; só leitura. Descrição que o cliente recebe: Os conectores da loja com o estado de cada um, a versão publicada, o cron e a última execução.

Sem parâmetros.

`list_runs`

Para saber se um conector está rodando bem e achar a execução que falhou. Pergunte “o que aconteceu nas últimas execuções do conector de clientes?”.

Permissão connect:read; só leitura. Descrição que o cliente recebe: As últimas execuções de um conector, da mais nova para a mais antiga, com estado e motivo da falha.

Parâmetro	Tipo	Obrigatório	Regras	Descrição
`connectorId`	string	sim	UUID	Id do conector, como list_connectors devolve
`limit`	integer	não	de 1 a 50	Quantas execuções, das mais novas (padrão 10)

`read_run`

Para entender uma falha: os passos, os contadores e o erro com a linha do código. Pergunte “por que a última execução falhou?”.

Permissão connect:read; só leitura. Descrição que o cliente recebe: Uma execução inteira: estado, contadores, os passos, o erro com a linha do código e a quarentena dela. Dados pessoais vêm mascarados.

Parâmetro	Tipo	Obrigatório	Regras	Descrição
`connectorId`	string	sim	UUID	Id do conector, como list_connectors devolve
`runId`	string	sim	UUID	Id da execução, como list_runs devolve

`read_quarantine`

Os registros que o outro sistema recusou e o motivo de cada um, para decidir se vale reprocessar.

Permissão connect:read; só leitura. Descrição que o cliente recebe: Os registros abertos na quarentena do conector, com o motivo e as tentativas. Dados pessoais vêm mascarados.

Parâmetro	Tipo	Obrigatório	Regras	Descrição
`connectorId`	string	sim	UUID	Id do conector, como list_connectors devolve
`limit`	integer	não	de 1 a 500	Quantos registros abertos (padrão 50)

`list_held_writes`

A primeira escrita em cada sistema fica guardada até uma pessoa confirmar. Mostra o que seria enviado.

Permissão connect:read; só leitura. Descrição que o cliente recebe: As escritas guardadas do conector: a primeira escrita em cada sistema espera a confirmação de uma pessoa.

Parâmetro	Tipo	Obrigatório	Regras	Descrição
`connectorId`	string	sim	UUID	Id do conector, como list_connectors devolve

`list_local_agents`

Se o agente instalado no computador da loja está conectado e o que ele alcança.

Permissão connect:read; só leitura. Descrição que o cliente recebe: Os agentes locais da loja, se estão conectados, o que alcançam e que conectores usam cada um.

Sem parâmetros.

`preview_operation`

Primeiro passo de toda mudança. Não muda nada: mostra o que vai acontecer e devolve o confirmationToken.

Permissão connect:operate; só leitura. Descrição que o cliente recebe: Primeiro passo de uma mudança: mostra o que vai acontecer e devolve um confirmationToken. Nada muda ainda. Mostre a prévia à pessoa antes de confirmar.

Parâmetro	Tipo	Obrigatório	Regras	Descrição
`operation`	string	sim	um de `enable`, `pause`, `run_now`, `reprocess_quarantine`, `confirm_held_write`	enable liga; pause pausa; run_now roda agora; reprocess_quarantine reprocessa a quarentena; confirm_held_write manda a primeira escrita guardada
`connectorId`	string	sim	UUID	Id do conector, como list_connectors devolve
`heldWriteId`	string	não	UUID	Só em confirm_held_write: a escrita guardada, como list_held_writes devolve
`itemIds`	string[]	não	UUID; de 1 a 500 itens	Só em reprocess_quarantine: os registros; sem ele vão os abertos mais novos

`confirm_operation`

Segundo passo: aplica a mudança da prévia. O cliente deve pedir o seu sim antes de chamar.

Permissão connect:operate; muda o Connect. Descrição que o cliente recebe: Segundo passo: aplica a mudança da prévia com o confirmationToken dela, depois que a pessoa concordou.

Parâmetro	Tipo	Obrigatório	Regras	Descrição
`confirmationToken`	string	sim	até 256 caracteres	O confirmationToken devolvido por preview_operation; vale uma vez, por 10 minutos

O que fica de fora

Construir, editar o código e publicar. São pela tela do Connect, pela conversa de construção ou pela CLI.
Segredos. Os valores são preenchidos só no formulário da tela.
Aprovar hosts e criar conectores. Só na tela.

Os erros das ferramentas vêm com code e message em português, os mesmos do catálogo de erros.

Endpoints do OAuth

Para quem implementa um cliente. Caminhos relativos a https://api-connect.zoppy.com.br (ou ao endereço da staging):

Método	Caminho	O que faz
GET	`/.well-known/oauth-protected-resource`	Metadados do recurso protegido (RFC 9728), o mesmo que o caminho com `/mcp`.
GET	`/.well-known/oauth-protected-resource/mcp`	Metadados do recurso protegido do MCP (RFC 9728): o recurso, o servidor de autorização e os escopos.
GET	`/.well-known/oauth-authorization-server`	Metadados do servidor de autorização (RFC 8414): endpoints, escopos, PKCE `S256`.
GET	`/.well-known/oauth-authorization-server/mcp`	O mesmo que o caminho sem `/mcp`, para clientes que procuram pelo caminho do recurso.
GET	`/oauth/authorize`	Início do login: confere o cliente, o PKCE e o recurso e manda para a tela de consentimento.
GET	`/oauth/consent`	Tela de consentimento mínima da própria API, para ambientes sem a do Connect. Em produção e staging, o consentimento abre na tela do Connect.
POST	`/oauth/token`	Troca o código pelo acesso e renova o acesso; reusar um refresh revoga a concessão inteira.
POST	`/oauth/register`	Registro dinâmico do cliente (RFC 7591), sem segredo de cliente (`token_endpoint_auth_method: none`).
POST	`/oauth/revoke`	Revoga a concessão do token informado (RFC 7009).
GET	`/oauth/authorizations/:requestId`	O pedido que a tela de consentimento mostra: o aplicativo, a loja e as permissões pedidas.
POST	`/oauth/authorizations/:requestId/decision`	A decisão da pessoa: aprovar com as permissões marcadas ou recusar.
POST	`/mcp`	O servidor MCP (Streamable HTTP), com `Authorization: Bearer <token>`.
ALL	`/mcp`	Qualquer outro método responde 405: o servidor só aceita POST.

Metadados do servidor de autorização em produção:

{
  "issuer": "https://api-connect.zoppy.com.br",
  "authorization_endpoint": "https://api-connect.zoppy.com.br/oauth/authorize",
  "token_endpoint": "https://api-connect.zoppy.com.br/oauth/token",
  "registration_endpoint": "https://api-connect.zoppy.com.br/oauth/register",
  "revocation_endpoint": "https://api-connect.zoppy.com.br/oauth/revoke",
  "scopes_supported": ["connect:read", "connect:operate", "connect:build"],
  "response_types_supported": ["code"],
  "response_modes_supported": ["query"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "revocation_endpoint_auth_methods_supported": ["none"],
  "authorization_response_iss_parameter_supported": true
}