Assistente de IA (MCP)

Conecte uma IA (Claude, ChatGPT ou sua IDE) aos dados da sua tenant via Model Context Protocol. A IA autentica com a sua conta — ela enxerga exatamente o que você enxerga, nada além.

1. Como funciona

Você aponta o cliente MCP para https://api.paygrid.tech/mcp.
O cliente descobre sozinho o OAuth em https://api.paygrid.tech/.well-known/oauth-authorization-server.
Você faz login com seu e-mail e senha e aprova o acesso numa tela que mostra o escopo (mcp:read, somente leitura).
A IA recebe um token de 15 minutos (renovado sozinho) e pode consultar — nunca alterar — seus dados.

A IA nunca vê sua senha. O acesso pode ser revogado a qualquer momento — basta desconectar o app no cliente, ou pedir ao suporte para derrubar a cadeia de tokens.

2. O que a IA pode fazer

Todas as tools são de leitura. Elas nunca criam, alteram, estornam nem disparam nada.

Pagamentos

get_transaction — buscar uma cobrança pelo ID
list_payments — listar pagamentos com filtros e paginação
get_payment — detalhe com estornos

Conciliação

get_reconciliation — confronto ao vivo contra o gateway; devolve só as divergências (status ou valor)
list_reconciliation_runs — histórico de execuções (agendada, manual, CSV/JSON), com contadores por execução
get_reconciliation_run — detalhe de uma execução, incluindo as linhas da lista do cliente que não existem na PayGrid (até 20 linhas por resposta, com o total informado)
list_reconciliation_results — estado por pagamento (conciliado, divergente, processando), com filtro opcional por execução

Use get_reconciliation para "o que está divergente agora" e as tools de histórico para "o que aconteceu na execução de ontem".

Verificação de identidade (KYC)

list_kyc_sessions — listar sessões, com filtro por status e paginação
get_kyc_session — detalhe da sessão: resultado de liveness, prova de idade, comparação facial, dados do documento e decisão manual

O detalhe do KYC contém dados pessoais (nome, CPF, data de nascimento) e links assinados para a selfie e o documento, que expiram em cerca de 15 minutos. O token da sessão e as chaves de armazenamento das imagens nunca são expostos. Trate esse conteúdo como dado sensível ao colar em uma conversa.

Clientes, webhooks e logs

list_customers / get_customer — pagadores
list_webhook_events / list_inbound_events — webhooks
search_logs — busca nos logs (sempre restrita à sua tenant)

Exemplos de perguntas: "ache a transação X", "quais pagamentos divergem do gateway hoje?", "como terminou a conciliação de ontem e o que não foi encontrado?", "as sessões de KYC que estão aguardando revisão manual", "resuma os erros da última hora".

3. Conectar no seu cliente MCP

O endpoint é https://api.paygrid.tech/mcp e a autenticação é OAuth descoberta automaticamente. No Claude Desktop, adicione um conector MCP remoto apontando para essa URL e siga o fluxo de login no navegador.

No Claude Code, no VS Code ou no opencode, registre o servidor remoto:

{
  "mcpServers": {
    "paygrid": {
      "type": "remote",
      "url": "https://api.paygrid.tech/mcp"
    }
  }
}

O cliente abre o navegador na primeira chamada. Depois do consentimento, a renovação do token é automática.

Limites

Somente leitura nesta fase: a IA não cria cobranças, não estorna e não dispara conciliação.
Tudo é escopado à sua tenant — inclusive os logs e o KYC.
Usuários com papel de operador não acessam as tools de conciliação, webhooks de entrada e logs, as mesmas que o painel esconde desse papel. KYC e pagamentos seguem liberados.
Vale o mesmo rate-limit da API.

Revogar acesso

Para revogar o acesso de um cliente MCP (e invalidar o refresh token), chame POST /oauth/revoke com o token (Bearer) ou o client_id. Depois de revogado, o assistente precisa de um novo consentimento no fluxo de login.