MCP (agentes de IA)

O que é

O Model Context Protocol (MCP) é um padrão aberto para conectar agentes de IA a sistemas externos. O servidor MCP do Pega Vez oferece 15 ferramentas prontas para tarefas do salão — consultar a agenda, achar horários livres, agendar, remarcar, buscar e cadastrar clientes, ver comandas, caixa e faturamento — que o agente chama em nome do token.

As ferramentas seguem as mesmas regras da API: o mesmo token, as mesmas permissões (interseção token × membro, inclusive o escopo “só a própria agenda”), o mesmo plano necessário e o mesmo limite de 600 requisições por minuto, somado ao uso da API. Por baixo, elas chamam os mesmos casos de uso dos endpoints: as regras de horário, as mensagens de erro e os webhooks disparados são os mesmos.


Endpoint	`https://api.pegavez.com.br/mcp`
Transporte	Streamable HTTP, sem sessão (stateless)
Autenticação	`Authorization: Bearer pv_...` (só token; cookie não vale)
Negócio	o do token (não há parâmetro de salão)
Nome do servidor	`pega-vez`

Sem sessão quer dizer que cada POST em /mcp é independente: o servidor não devolve Mcp-Session-Id e não guarda estado entre chamadas. O cliente só precisa mandar o token em toda requisição.

Conectar no Claude Code

claude mcp add --transport http pegavez https://api.pegavez.com.br/mcp \
  --header "Authorization: Bearer pv_..."

Depois, rode /mcp dentro do Claude Code para conferir a conexão e ver as ferramentas.

Para compartilhar a configuração com a equipe sem expor o token, use um .mcp.json no projeto com o token numa variável de ambiente (cada pessoa define a sua):

{
  "mcpServers": {
    "pegavez": {
      "type": "http",
      "url": "https://api.pegavez.com.br/mcp",
      "headers": {
        "Authorization": "Bearer ${PEGAVEZ_TOKEN}"
      }
    }
  }
}

Outros clientes

Qualquer cliente MCP que aceite um servidor remoto Streamable HTTP com header personalizado funciona. A configuração costuma ter este formato:

{
  "url": "https://api.pegavez.com.br/mcp",
  "headers": {
    "Authorization": "Bearer pv_..."
  }
}

Para testar a conexão sem cliente nenhum, mande o initialize do protocolo com curl:

curl -s https://api.pegavez.com.br/mcp \
  -H "Authorization: Bearer $PEGAVEZ_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "teste", "version": "1.0" }
    }
  }'

Como não há sessão, a requisição seguinte já pode listar as ferramentas:

curl -s https://api.pegavez.com.br/mcp \
  -H "Authorization: Bearer $PEGAVEZ_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

OAuth ainda não é suportado

Por enquanto o servidor aceita só token Bearer no header. Clientes que exigem login por OAuth para servidores remotos (por exemplo, os conectores personalizados do Claude no navegador e no app) ainda não conseguem se conectar. O suporte a OAuth está planejado para uma próxima fase e vai aparecer no changelog.

Formatos

Datas: AAAA-MM-DD, dia de calendário no fuso do negócio (ex.: 2026-11-03).
Horários enviados: AAAA-MM-DDTHH:mm na hora local do negócio (ex.: 2026-11-03T14:30). Um offset explícito também vale (2026-11-03T14:30-03:00 ou ...Z).
Horários devolvidos: ISO 8601 com o offset do negócio (ex.: 2026-11-03T14:30:00-03:00). Os horários livres de consultar_horarios_disponiveis vêm como HH:mm, agrupados por data.
Dinheiro: reais (BRL), número com ponto decimal (89.9 = R$ 89,90).
Respostas: JSON estruturado (structuredContent), em camelCase, com enums como texto ("Confirmed"). Campos sem valor são omitidos.
Listas: paginadas com page e pageSize (até 50 por página) ou limitadas (a agenda para em 200 agendamentos e avisa com truncated: true).

Ferramentas

São 15: 9 de leitura e 6 de escrita. A coluna Tipo segue as anotações MCP de cada ferramenta (readOnlyHint, destructiveHint, idempotentHint), que os clientes usam para decidir quando pedir confirmação.

Ferramenta	Título	Tipo	Permissão
`listar_servicos_e_profissionais`	Listar serviços e profissionais	leitura	qualquer membro
`consultar_horarios_disponiveis`	Consultar horários disponíveis	leitura	`agenda.view`
`agenda_do_periodo`	Agenda do período	leitura	`agenda.view`
`consultar_agendamento`	Consultar agendamento	leitura	`agenda.view`
`buscar_clientes`	Buscar clientes	leitura	`customers.view`
`historico_do_cliente`	Histórico do cliente	leitura	`customers.view`
`listar_comandas`	Listar comandas	leitura	`checkout.operate`
`resumo_do_caixa`	Resumo do caixa	leitura	`cash.manage` ou `checkout.operate`
`faturamento_do_periodo`	Faturamento do período	leitura	`reports.view`
`agendar`	Agendar	escrita	`agenda.edit`
`remarcar_agendamento`	Remarcar agendamento	escrita (idempotente)	`agenda.edit`
`cancelar_agendamento`	Cancelar agendamento	escrita destrutiva	`agenda.edit`
`mudar_status_do_agendamento`	Mudar status do agendamento	escrita	`agenda.edit`
`cadastrar_cliente`	Cadastrar cliente	escrita	`customers.edit`
`editar_cliente`	Editar cliente	escrita (idempotente)	`customers.edit`

As ferramentas de leitura também são idempotentes. Nos parâmetros abaixo, os marcados com * são obrigatórios.

Leitura

`listar_servicos_e_profissionais`

Lista os serviços ativos (id, nome, categoria, duração em minutos, preço padrão em BRL e se aparece na página pública) e os profissionais ativos com os serviços que cada um faz, além do nome e do fuso do negócio. É a primeira chamada de quase todo fluxo: dela saem os ids usados para consultar horários e agendar.

Permissão: qualquer membro. Os profissionais só vêm com agenda.view (com escopo “próprio”, só o próprio profissional); sem isso, a lista de profissionais vem vazia.
Parâmetros: search (trecho do nome do serviço).
Exemplo de pedido ao agente: “Quais serviços o salão oferece e quanto custa a barba?”

`consultar_horarios_disponiveis`

Horários livres para os serviços informados, por profissional, em até 7 dias a partir da data. Considera jornada, folgas, bloqueios e agendamentos e não lista horários que já passaram. A duração é a soma dos serviços com cada profissional; quando um profissional não tem horário por outro motivo (ex.: não faz o serviço), vem unavailableReason.

Permissão: agenda.view.
Parâmetros: serviceIds* (ids dos serviços, na ordem do atendimento), date (primeiro dia, AAAA-MM-DD; padrão: hoje), days (1 a 7; padrão: 1), professionalId (só este profissional), excludeAppointmentId (na remarcação: o horário do próprio agendamento conta como livre).
Exemplo de pedido: “Quais horários a Ana tem livres amanhã à tarde para corte?”

`agenda_do_periodo`

Agendamentos e bloqueios de um dia ou de um intervalo de até 7 dias, do mais cedo ao mais tarde. Cada agendamento traz horário, status, profissional, cliente, serviços, total em BRL e as ações possíveis agora (allowedActions). Com escopo “só a própria agenda”, vêm apenas os agendamentos do próprio profissional. A lista para em 200 agendamentos (truncated: true): peça um período menor ou filtre o profissional.

Permissão: agenda.view.
Parâmetros: from (primeiro dia, AAAA-MM-DD; padrão: hoje), to (último dia, inclusive, no máximo 6 dias depois de from; padrão: o mesmo dia), professionalId, includeCancelled (padrão: false; os “não compareceu” sempre vêm).
Exemplo de pedido: “Como está a agenda do Bruno nesta semana?”

`consultar_agendamento`

Detalhe de um agendamento pelo id: horário, status, profissional, cliente, serviços, total em BRL, observação, motivo do cancelamento e as ações possíveis agora. O telefone do cliente só vem com customers.view.

Permissão: agenda.view.
Parâmetros: appointmentId*.

`buscar_clientes`

Busca clientes por parte do nome, do e-mail ou por dígitos do telefone (a partir de 3), em ordem alfabética, com contato, selo de reputação (New, Trusted, Attention, Risk — uso interno, nunca para mostrar ao cliente) e última visita.

Permissão: customers.view.
Parâmetros: search (vazio lista todos), page (padrão: 1), pageSize (1 a 50; padrão: 20).
Exemplo de pedido: “Ache a cliente Maria Souza.”

`historico_do_cliente`

Cadastro de um cliente (contato, selo, indicadores dos últimos 12 meses: comparecimento, faltas, cancelamentos e ticket médio) e os agendamentos dele, do mais recente ao mais antigo. Observações e data de nascimento só vêm com customers.edit. Os agendamentos exigem também agenda.view (com escopo “próprio”, só os do próprio profissional); sem ela, vem só o cadastro.

Permissão: customers.view.
Parâmetros: customerId*, page (padrão: 1), pageSize (1 a 50; padrão: 10).

`listar_comandas`

Lista as comandas da mais nova para a mais antiga, com número, status, cliente, data de movimento, descrição, total, gorjetas, valor pago e saldo devedor (fiado), em BRL.

Permissão: checkout.operate.
Parâmetros: status (Open, Closed ou Cancelled), from e to (período pela data de movimento, AAAA-MM-DD), customerId, search (número da comanda ou parte do nome do cliente), withBalance (só as fechadas com saldo devedor; padrão: false), page (padrão: 1), pageSize (1 a 50; padrão: 20).

`resumo_do_caixa`

Diz se há caixa aberto. Para quem gerencia o caixa (cash.manage), traz também o fundo de troco, as entradas e saídas, o valor esperado na gaveta e os recebimentos por forma de pagamento desde a abertura, em BRL. Com só checkout.operate, vem apenas se está aberto e desde quando.

Permissão: cash.manage ou checkout.operate.
Parâmetros: nenhum.

`faturamento_do_periodo`

Faturamento das comandas fechadas entre duas datas (pela data local do fechamento, até 366 dias): total bruto, descontos, líquido, ticket médio e gorjetas, por dia, por profissional e os 10 serviços que mais faturaram. Gorjetas ficam fora do faturamento (são dos profissionais).

Permissão: reports.view (e os relatórios no plano, incluídos no Equipe e no Negócio).
Parâmetros: from* e to* (AAAA-MM-DD, inclusive), professionalId (só os itens e gorjetas deste profissional).
Exemplo de pedido: “Quanto o salão faturou em outubro?”

Escrita

As ferramentas de escrita devolvem o agendamento ou o cliente como ficou depois da mudança. Com a conta bloqueada, todas respondem erro (veja Erros).

`agendar`

Cria um agendamento confirmado para um cliente existente (customerId, de buscar_clientes) ou para um cliente novo (newCustomerName com telefone ou e-mail; se o telefone ou e-mail já existir, usa esse cadastro). Horário ocupado ou fora da jornada volta como erro com o motivo; encaixe fora da jornada só com allowOutsideWorkingHours (nunca sobre outro agendamento).

Permissão: agenda.edit. Não é idempotente: chamar duas vezes cria dois agendamentos (o MCP não tem Idempotency-Key).
Parâmetros: professionalId*, startsAt* (AAAA-MM-DDTHH:mm na hora local, ou com offset), serviceIds* (1 a 10, na ordem do atendimento), customerId ou newCustomerName (com newCustomerPhone — com DDD, ex.: 11 99999-8888 — ou newCustomerEmail), notes (observação interna), allowOutsideWorkingHours (padrão: false).
Exemplo de pedido: “Agende um corte com a Ana amanhã às 14h para a Maria Souza.”

`remarcar_agendamento`

Move um agendamento para outro horário e, se quiser, para outro profissional; os serviços continuam os mesmos. Confira antes o horário com consultar_horarios_disponiveis passando excludeAppointmentId.

Permissão: agenda.edit.
Parâmetros: appointmentId*, startsAt* (novo início), professionalId (novo profissional; padrão: o mesmo), allowOutsideWorkingHours (padrão: false).

`cancelar_agendamento`

Cancela um agendamento solicitado ou confirmado e libera o horário. Não dá para desfazer: o agente deve confirmar com a pessoa antes de chamar.

Permissão: agenda.edit.
Parâmetros: appointmentId*, cancelledBy* (Customer — o cliente pediu, conta na reputação dele — ou Salon), reason (motivo).

`mudar_status_do_agendamento`

Avança o atendimento. As ações possíveis de cada agendamento vêm em allowedActions; para cancelar, use cancelar_agendamento.

`action`	Efeito
`Confirm`	Solicitado → Confirmado
`Arrive`	Cliente chegou (também corrige um “não compareceu”)
`Start`	Chegou → Em atendimento
`Complete`	Chegou / Em atendimento → Concluído
`MarkNoShow`	Não compareceu (liberado alguns minutos depois do início)

Permissão: agenda.edit.
Parâmetros: appointmentId*, action*, at (hora real em Arrive, Start e Complete, AAAA-MM-DDTHH:mm na hora local; padrão: agora).

`cadastrar_cliente`

Cadastra um cliente novo. Telefone ou e-mail que já existem no negócio voltam como erro: procure antes com buscar_clientes.

Permissão: customers.edit.
Parâmetros: name*, phone (com DDD), email, birthDate (AAAA-MM-DD), notes (observações internas).

`editar_cliente`

Altera o cadastro de um cliente. Envie só os campos que mudam: os omitidos continuam como estão. Para apagar telefone, e-mail, nascimento ou observações, envie texto vazio (""). Cliente anonimizado não pode ser alterado.

Permissão: customers.edit.
Parâmetros: customerId*, name, phone, email, birthDate, notes, blockedFromOnlineBooking (true bloqueia e false libera o agendamento online deste cliente).

Erros

Há dois níveis de erro.

Na requisição HTTP, antes de qualquer ferramenta rodar — como na API:

Status	Quando
`401`	Sem token, com token inválido, expirado, revogado ou de membro desativado, ou só com cookie. Vem com `WWW-Authenticate: Bearer`.
`403` `plan_feature`	O negócio está no plano Solo (integrações são dos planos Equipe e Negócio). Vale para qualquer chamada, inclusive o `initialize`.
`429`	Passou de 600 requisições por minuto no token (API e MCP somados). Espere os segundos do `Retry-After`.

Dentro da ferramenta, a resposta HTTP é 200 e o resultado vem com isError: true e uma mensagem em português, pensada para o agente repassar a quem está conversando. Isso vale para:

falta de permissão — “Sem permissão para esta ferramenta: o token (ou o membro que o criou) precisa de “Ver a agenda” (agenda.view).” (lembre da interseção);
conta bloqueada (assinatura inativa) — as ferramentas de leitura continuam funcionando; as de escrita respondem “Assinatura inativa: o negócio está em modo somente leitura.”;
regra de negócio — horário ocupado, fora da jornada, status que não permite a ação, cliente anonimizado;
duplicidade — telefone ou e-mail de cliente já cadastrado;
validação — data em formato errado, campo obrigatório faltando;
não encontrado — inclusive registros de outro negócio, que nunca aparecem.

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "isError": true,
    "content": [
      { "type": "text", "text": "O horário acabou de ser ocupado." }
    ]
  }
}