O servidor MCP da Peatch
A Peatch expõe um servidor MCP. Qualquer cliente que fale o Model Context Protocol pode se conectar, ler o espaço de trabalho que uma pessoa aprovou (vagas abertas, candidatos, entrevistas, pontuação e briefs de vaga) e propor alterações que só se aplicam depois que essa pessoa as confirma na Peatch.
O que é
Um servidor MCP é uma forma padronizada de um cliente de IA chamar um conjunto de ferramentas documentadas. A Peatch implementa a metade servidor. Seu cliente implementa a outra, e os dois combinam pelo protocolo em vez de uma integração sob medida.
Qualquer cliente compatível funciona. Nada nesta página é específico de um fornecedor.
Endpoint
- Endereço
- https://peatch.ai/api/mcp
- Revisão do protocolo
- 2025-06-18
- Transporte
- JSON-RPC 2.0 sobre HTTP POST, um objeto por requisição. Sem SSE, sem streaming, sem cabeçalho de sessão, e lotes em array são recusados.
- Métodos
- initialize, ping, tools/list, tools/call
- Capacidades
- Somente ferramentas. Recursos e prompts não são implementados e respondem método não encontrado.
- Corpo máximo da requisição
- 64 KiB
Autorização
OAuth 2.1. Não há chave de API para colar nem segredo de cliente para guardar.
- Descoberta
- Os dois documentos de metadados são servidos, então um cliente encontra o servidor de autorização apenas a partir do recurso. Um token recusado volta como 401 com um desafio WWW-Authenticate nomeando a URL de metadados.
- Registro do cliente e PKCE
- O registro dinâmico é aberto e não autenticado, e emite apenas clientes públicos. PKCE é obrigatório e somente S256: um método ausente ou plain é recusado, no endpoint de autorização e de novo no de token.
- Durações
- O código de autorização vive 60 segundos e é de uso único. O token de acesso vive uma hora. Os tokens de atualização giram a cada uso mas herdam o vencimento original: 30 dias são um teto absoluto desde o primeiro consentimento, depois disso uma pessoa consente de novo. Reutilizar um token já consumido revoga toda a família.
- Um token, um espaço de trabalho
- O espaço é escolhido pela pessoa no consentimento e fica fixado no token. Nenhuma requisição posterior pode influenciá‑lo. A associação é reverificada a cada chamada: remover alguém do espaço interrompe seus tokens na hora, sem etapa de revogação.
- Revogação
- Não há endpoint RFC 7009. A revogação é uma ação de produto: um administrador do espaço remove a conexão nas configurações da Peatch, o que revoga toda a concessão, acesso e atualização inclusive.
O que é servido
Vinte ferramentas de leitura e vinte e uma de escrita. O endpoint só lista uma ferramenta se o nome dela estiver numa lista de autorização do servidor e a classe declarada for leitura ou escrita. Uma leitura roda na hora. Uma escrita nunca roda na chamada: ela devolve uma ação pendente com um link de confirmação, e só roda se a pessoa que conectou o cliente a aprovar na Peatch em até 24 horas. A ferramenta de leitura get_pending_action informa depois ao cliente se ela foi aprovada e o que devolveu.
Vagas e seu funil de convites
list_batches, get_batch_details, get_batch_candidates, analyze_batch, send_batch_invites, create_batch, update_batch, add_invite_to_batch
Análise do funil e das desistências
analyze_pipeline_health, analyze_rejection_patterns
Candidatos e seus dossiês
get_candidate_details, compare_candidates, get_personality_profile, generate_candidate_brief, update_hiring_status, update_invite_hiring_status, create_job_requirement, add_to_shortlist, remove_from_shortlist, update_shortlist_status
Modelos de entrevista e configuração de pontuação
list_scenarios, list_topics, get_scoring_agent, analyze_score_calibration, create_scenario, create_scenario_from_onboarding, update_scenario, delete_scenario, create_topic, update_topic, delete_topic, create_scoring_agent, update_scoring_agent
Agendamento
check_calendar_status, list_scheduled_interviews, schedule_interview
Briefs de vaga
get_role_brief, get_role_brief_gaps, create_role_brief, update_role_brief
Acompanhamento das alterações propostas
get_pending_action
Esse número é o que a porta serve hoje, não um contrato fixo. Nomes de ferramentas são identificadores estáveis e não são traduzidos.
Limites de uso
Quatro limites se aplicam, e o primeiro é o que você vai encontrar.
- 60 requisições por minuto por IP de cliente, antes da autenticação. É o limite que pesa para um cliente isolado.
- 300 requisições por minuto por token, depois da autenticação.
- 60 chamadas de ferramenta por minuto por token.
- 240 chamadas por minuto por espaço de trabalho, compartilhadas entre seus tokens.
As janelas são fixas e alinhadas ao relógio, não deslizantes. Uma chamada recusada devolve 429; o que se deve interpretar é o código legível por máquina, nunca a mensagem, que é localizada.
O que ele não pode fazer sozinho
Toda alteração espera por uma pessoa, e quem impõe isso é o servidor, não o cliente.
- Ele nunca envia e‑mail, e não adiciona nenhum candidato sem a sua confirmação.
- Ele não pode mudar uma nota, uma rubrica ou uma vaga sem a sua confirmação.
- Ele não pode descartar ninguém sem a sua confirmação, e nunca enquanto o candidato ainda está na entrevista.
Um link de confirmação expira em 24 horas, e a alteração só se aplica no espaço escolhido no consentimento. Algumas ferramentas chamam um modelo de linguagem para compor a resposta, então uma chamada não é gratuita mesmo quando não muda nada.
Conectar
- 1
Declare o servidor no seu cliente
Aponte seu cliente MCP para o endereço acima. Clientes com registro dinâmico não precisam de mais nada.
- 2
Uma pessoa aprova
A Peatch mostra qual cliente está pedindo acesso e a qual espaço ele vai chegar. Um administrador do espaço aprova, e só então um token é emitido.
- 3
Chame as ferramentas
Rode tools/list para ver o que este espaço expõe, depois tools/call.
O que ele responde na prática
- Para quais vagas estou contratando agora?
- Quem são os cinco melhores candidatos desta vaga?
- Onde meu funil está travando, e desde quando?
- O que falta no meu brief da vaga?
As respostas vêm do espaço aprovado, e cada número remete a uma entrevista que uma pessoa pode abrir.
Incluído em todos os planos
Sem adicional e sem licença separada. Se você tem um espaço de trabalho na Peatch, pode conectar um cliente a ele.