Consulte as treze ferramentas do MCP da OctoSolve, seus parâmetros, resultados, riscos e recusas.

Ferramentas

O servidor oferece treze ferramentas em quatro grupos. Risco Baixo indica leitura. Risco Médio altera dados internos. Risco Alto pode ocupar a agenda de uma pessoa ou avisar o cliente final.

Listas devolvem data, has_more e next_cursor. O limite padrão no MCP é 20 itens, e o máximo é 100. Use next_cursor como cursor na chamada seguinte sem alterar os filtros.

O CPF não sai pelo MCP, inclusive depois de criar ou atualizar um contato. Se a sua integração precisa desse dado, consulte o contato diretamente pela API REST com uma chave autorizada.

Contatos

`buscar_contatos`

Propriedade	Valor
Grupo	Contatos
Risco	Baixo
Exige	Nenhum campo obrigatório. Aceita `telefone`, `q`, `status`, `tag`, `limit` e `cursor`
Limites	`q` de 2 a 80 caracteres, `tag` com até 40, `limit` de 1 a 100, padrão 20
Valores de `status`	`novo`, `ativo`, `inativo` ou `bloqueado`
Devolve	Lista paginada de contatos, sem CPF

Pode recusar busca curta, limite fora da faixa, status inválido ou cursor reaproveitado com filtros diferentes.

`ver_contato`

Propriedade	Valor
Grupo	Contatos
Risco	Baixo
Exige	`contact_id`
Devolve	Um contato com dados cadastrais, identidades de canal, tags, situação e data de atualização, sem CPF

Um identificador inexistente ou pertencente a outra conta é tratado como contato não encontrado.

`criar_contato`

Propriedade	Valor
Grupo	Contatos
Risco	Médio
Exige	`telefone`
Aceita	`nome`, `email`, `cidade`, `data_nascimento`, `observacoes`, `tags` e `status`
Limites	Telefone de 10 a 20 caracteres na entrada, nome e cidade com até 120, observações com até 2.000, no máximo 20 tags
Devolve	O contato criado, sem CPF

O telefone precisa resultar em 10 a 15 dígitos com DDI e DDD. Telefone já cadastrado é conflito. E-mail, data ou situação inválidos são recusados. Uma repetição idêntica na mesma faixa de dez minutos devolve o resultado original em vez de criar duplicata.

`atualizar_contato`

Propriedade	Valor
Grupo	Contatos
Risco	Médio
Exige	`contact_id`
Aceita	`nome`, `email`, `cidade`, `data_nascimento`, `observacoes`, `tags` e `status`
Limites	Nome e cidade com até 120 caracteres, observações com até 2.000, no máximo 20 tags
Devolve	O contato atualizado, sem CPF

Somente os campos enviados são alterados. O valor anterior é sobrescrito. A ferramenta recusa identificador inexistente, e-mail, data ou situação inválidos.

`Catalogo`

`listar_servicos`

Propriedade	Valor
Grupo	`Catalogo`
Risco	Baixo
Exige	Nenhum campo obrigatório
Aceita	`ativo`, `q`, `limit` e `cursor`
Limites	`q` de 2 a 80 caracteres, `limit` de 1 a 100, padrão 20
Padrão	`ativo: true`
Devolve	Lista paginada com nome, descrição, duração, preços, categoria e regras do serviço

Pode recusar busca curta, limite fora da faixa ou cursor reaproveitado com filtros diferentes.

`ver_servico`

Propriedade	Valor
Grupo	`Catalogo`
Risco	Baixo
Exige	`service_id`
Devolve	Um serviço, inclusive quando inativo

Um identificador inexistente ou pertencente a outra conta é tratado como serviço não encontrado.

Equipe

`listar_profissionais`

Propriedade	Valor
Grupo	Equipe
Risco	Baixo
Exige	Nenhum campo obrigatório
Aceita	`ativo`, `servico_id`, `limit` e `cursor`
Limites	`servico_id` em UUID, `limit` de 1 a 100, padrão 20
Padrão	`ativo: true`
Devolve	Lista paginada com perfil, estado da agenda e serviços atendidos, sem e-mail do profissional

Pode recusar UUID inválido, limite fora da faixa ou cursor reaproveitado com filtros diferentes.

`ver_profissional`

Propriedade	Valor
Grupo	Equipe
Risco	Baixo
Exige	`professional_id`
Devolve	Perfil, estado da agenda e serviços atendidos pelo profissional, sem e-mail

Um identificador inexistente ou pertencente a outra conta é tratado como profissional não encontrado.

Agenda

`ver_horarios_livres`

Propriedade	Valor
Grupo	Agenda
Risco	Baixo
Exige	`servico_id` em UUID e `data` no formato `AAAA-MM-DD`
Aceita	`dias` e `profissional_id` em UUID
Limites	`dias` de 1 a 7, padrão 1, data no máximo 365 dias à frente, até 40 combinações de dia e profissional
Devolve	Duração do serviço e slots por dia e profissional. `inicio` e `fim` vêm em UTC com `Z`

A ferramenta recusa serviço ou profissional inexistente, agenda não conectada, intervalo amplo demais e data distante demais. Uma indisponibilidade temporária da agenda também gera recusa. A consulta não reserva o horário.

`listar_agendamentos`

Propriedade	Valor
Grupo	Agenda
Risco	Baixo
Exige	Nenhum campo obrigatório
Aceita	`contact_id`, `profissional_id`, `servico_id`, lista `status`, `de`, `ate`, `limit` e `cursor`
Limites	`limit` de 1 a 100, padrão 20
Período padrão	Sem `de` e `ate`, começa 30 dias antes do momento atual e segue para o futuro
Devolve	Lista paginada e cronológica de agendamentos

de e ate aceitam data ou data e hora ISO. Sem fuso, o horário de Brasília é assumido. A ferramenta recusa período invertido, situação inválida e cursor usado com filtros diferentes.

`ver_agendamento`

Propriedade	Valor
Grupo	Agenda
Risco	Baixo
Exige	`appointment_id`
Devolve	Estado atual e todos os campos públicos do agendamento. Datas vêm em UTC com `Z`

Consulte esta ferramenta antes de alterar. Um identificador inexistente ou pertencente a outra conta é tratado como agendamento não encontrado.

`criar_agendamento`

Propriedade	Valor
Grupo	Agenda
Risco	Alto
Exige	`contact_id`, `servico_id` e `data_hora` em ISO
Aceita	`profissional_id`, `duracao_minutos`, `valor`, `notas` e `notificar_whatsapp`
Limites	Duração de 5 a 600 minutos, notas com até 2.000 caracteres
Padrão	`notificar_whatsapp: false`
Devolve	O agendamento criado

Use em data_hora o inicio devolvido por ver_horarios_livres, sem modificar. A ferramenta recusa horário ocupado, serviço inativo, serviço com pagamento antecipado, entidade inexistente e profissional que não pode atender. Se houver conflito, consulte os horários outra vez e escolha outro. Uma repetição idêntica na mesma faixa de dez minutos devolve o resultado original.

`alterar_agendamento`

Propriedade	Valor
Grupo	Agenda
Risco	Alto
Exige	`appointment_id`
Aceita	`profissional_id`, `data_hora`, `duracao_minutos`, `status`, `valor`, `motivo_cancelamento` e `notas`
Limites	Duração de 5 a 600 minutos, motivo com até 500 caracteres, notas com até 2.000
Devolve	O agendamento atualizado

Situações aceitas: agendado, confirmado, realizado, no_show, cancelado, aguardando_pagamento, cancelado_por_nao_pagamento, cancelado_estornado e cancelado_lgpd.

A ferramenta aplica estas recusas:

Ocorrência de série não pode ser alterada.
motivo_cancelamento só pode acompanhar status: "cancelado".
Remarcação só pode terminar em agendado ou confirmado.
cancelado, realizado e no_show são estados finais.
profissional_id: null e duracao_minutos: null não são aceitos.
Horário ocupado é conflito e exige uma nova consulta de disponibilidade.

Cancelar não tem volta. Para atender novamente, crie outro agendamento. Se uma repetição receber transição proibida e o estado atual já for o solicitado, considere que a primeira alteração foi concluída.

Recusas comuns a todas

Uma chamada também pode ser recusada quando:

O servidor MCP ou a ferramenta está desligado.
A chave está ausente, inválida, revogada, suspensa ou vencida.
Uma chave read tenta usar ferramenta de escrita.
O plano não inclui MCP ou a conta está suspensa.
Um campo obrigatório está ausente ou um argumento não atende ao formato e ao limite.
O limite de requisições foi atingido.

A IA recebe a mensagem de negócio em português como erro de ferramenta. Falhas inesperadas devolvem somente uma mensagem genérica, sem detalhes técnicos.

Ferramentas

On this page