Servidor MCP

O servidor MCP do Festero deixa um assistente de IA consultar os dados da sua empresa e responder em linguagem natural: quanto foi vendido no mês, quais parcelas estão vencidas, em que etapa do funil está cada oportunidade. O MCP (Model Context Protocol) é o padrão que clientes como o Claude Code e o Cursor usam para conversar com ferramentas externas.

As ferramentas são as mesmas rotas da API de leitura, com o mesmo escopo, o mesmo formato de resposta e o mesmo isolamento por empresa. Todas são somente de leitura: o assistente nunca altera nada no Festero.

Exemplo ilustrativo: os valores são fictícios.

Você

Quais recebíveis estão vencidos?

Ferramenta MCP chamada

list_receivables{ "status": "overdue" }

Assistente

Há 3 recebíveis vencidos, somando R$ 4.200,00 em aberto. O mais antigo venceu em 10/10, do casamento de Camila e Rafael.

Endereço

Item	Valor
URL do servidor	https://platform.festero.com.br/v1/mcp
Transporte	HTTP, sem sessão (cada chamada é independente)
Autenticação	Cabeçalho Authorization: Bearer <chave MCP ou token>
Protocolo	Revisão 2026-07-28. Clientes na revisão 2025-11-25 também funcionam.

Autenticação

O servidor aceita o cabeçalho Authorization: Bearer ... de duas formas:

Forma	Como é	Quando usar
Chave MCP (fk_mcp_...)	Uma chave fixa, criada para uma credencial.	A forma recomendada para ligar um assistente: é só colocá-la na configuração do cliente.
Token de acesso	O mesmo token de 60 minutos das rotas da API (Autenticação).	Clientes ou programas que pedem e renovam o token sozinhos.

Nos dois casos valem os escopos e o plano da credencial.

Criar uma chave MCP

1. No Festero, abra API do Festero no menu lateral. Você precisa da permissão Gerenciar a API pública e as chaves MCP e de uma credencial Ativa (Autenticação).
2. No cartão da credencial, na seção Chaves MCP, clique em Criar chave MCP.
3. Copie a chave e o endereço do servidor.

A chave aparece uma única vez

Depois de fechar a janela, não dá para ver a chave de novo. Guarde-a como uma senha. Se perder ou vazar, revogue a chave (botão Revogar ao lado dela) e crie outra.

Como funciona:

• A chave herda os escopos da credencial a que pertence: ela lê exatamente o que a credencial lê, e nada além.
• Cada credencial pode ter até 5 chaves MCP ativas. Use uma por assistente ou por pessoa, para revogar uma sem afetar as outras.
• Cada chave tem a sua data de vencimento, mostrada na tela.
• Se a credencial for revogada, suspensa ou expirar, as chaves dela deixam de funcionar junto.
• As chamadas do assistente contam na cota de uso da credencial.

Como conectar, cliente a cliente

Os clientes abaixo enviam o cabeçalho Authorization configurado por você. Troque fk_mcp_... pela sua chave.

Claude Code

claude mcp add --transport http festero https://platform.festero.com.br/v1/mcp \
  --header "Authorization: Bearer fk_mcp_..."

Cursor

No arquivo mcp.json do Cursor, acrescente o servidor:

{
  "mcpServers": {
    "festero": {
      "url": "https://platform.festero.com.br/v1/mcp",
      "headers": { "Authorization": "Bearer fk_mcp_..." }
    }
  }
}

Outros clientes MCP

Qualquer cliente que consiga se conectar a um servidor MCP por HTTP e enviar um cabeçalho Authorization fixo funciona. Informe a URL https://platform.festero.com.br/v1/mcp e o cabeçalho Authorization: Bearer fk_mcp_....

Claude.ai na web e ChatGPT

Por enquanto, a conexão é feita por clientes que enviam o cabeçalho Authorization. O servidor ainda não oferece login por OAuth, que é o que os conectores web do Claude.ai e do ChatGPT pedem; por isso não documentamos essas duas opções.

Ferramentas

São 10 ferramentas, todas de leitura. Os nomes e as descrições das ferramentas são em inglês, porque o assistente é quem as lê; o assistente responde a você em português normalmente. O resultado de cada uma é o mesmo JSON da rota equivalente da API.

Ferramenta	O que faz	Escopo	Parâmetros
list_opportunities	Lista as oportunidades de venda do funil, da alteração mais antiga para a mais recente.	crm:read	status, stageId, limit, cursor
get_opportunity	Busca uma oportunidade pelo identificador.	crm:read	id
list_pipeline_stages	Lista as etapas do funil de vendas, na ordem do quadro.	crm:read	nenhum
list_visits	Lista as visitas de clientes interessados ao espaço.	visits:read	status, startFrom, startTo, limit, cursor
list_events	Lista os eventos da empresa.	events:read	status, eventDateFrom, eventDateTo, limit, cursor
get_event	Busca um evento pelo identificador.	events:read	id
list_quotes	Lista os orçamentos enviados aos clientes.	quotes:read	status, eventDateFrom, eventDateTo, limit, cursor
get_quote	Busca um orçamento pelo identificador, com opções e itens.	quotes:read	id
list_receivables	Lista os recebíveis (parcelas a receber).	finance:read	status, dueFrom, dueTo, eventId, limit, cursor
sales_summary	Totais de vendas e recebíveis de um período, em uma só chamada.	finance:read	from, to

Os valores aceitos em status e o formato das datas (yyyy-MM-dd) são os mesmos da API de leitura: veja CRM, Visitas, Eventos, Orçamentos e Financeiro.

Diferenças em relação às rotas da API:

• Páginas menores. O limit vai de 1 a 50 (padrão 20); um valor fora desse intervalo é ajustado. A paginação usa nextCursor, como na API.
• Sem updatedSince. O filtro por alteração não existe nas ferramentas.
• Sem busca por id de visita ou de recebível. Para esses dois recursos, use a lista.
• Para totais, use sales_summary. Em vez de pedir ao assistente que some a lista de eventos ou de recebíveis, ele pode chamar sales_summary e receber os totais prontos, com os mesmos números do relatório de Vendas do Festero. Período de até 366 dias.

Uma ferramenta chamada sem o escopo da credencial devolve um erro scope_missing que informa o escopo que falta, sem nenhum dado.

Perguntas para fazer

Depois de conectar, pergunte em português do jeito que você falaria com um colega:

Pergunta	Ferramenta que o assistente costuma usar
Quanto vendemos em outubro e quanto ainda falta receber?	sales_summary
Quais parcelas estão vencidas?	list_receivables com status igual a overdue
Que eventos temos em março de 2027?	list_events com eventDateFrom e eventDateTo
Quais orçamentos foram enviados e ainda não foram aprovados?	list_quotes com status igual a sent
Mostre os itens do orçamento do casamento da Camila.	list_quotes e get_quote
Quais visitas estão marcadas para esta semana?	list_visits com status igual a scheduled, startFrom e startTo
Quantas oportunidades abertas temos em cada etapa do funil?	list_pipeline_stages e list_opportunities

O assistente só enxerga o que a credencial permite, e nunca vê telefone, e-mail, custo ou margem.

Os dados passam pelo assistente

Tudo que o assistente consulta é enviado ao serviço de IA que você conectou. Conecte apenas assistentes que a sua empresa aprova para tratar esses dados.

Problemas comuns

O que aparece	Causa	O que fazer
Erro 401 ao conectar, com token_invalid	Cabeçalho Authorization ausente ou chave digitada errada.	Confira se o valor é Bearer seguido da chave inteira, começando por fk_mcp_.
Erro 401 com credential_revoked	A chave foi revogada ou expirou, ou a credencial dela foi revogada, suspensa ou expirou.	Crie uma chave nova em API do Festero.
Uma ferramenta responde scope_missing	A credencial não tem o conjunto de dados daquela ferramenta.	Crie uma credencial com o escopo que falta, e uma chave MCP para ela.
Uma ferramenta responde not_found	O identificador não existe, ou o recurso é de outra empresa.	Confira o identificador.
403 com access_denied e a mensagem "Origin not allowed"	A requisição veio de um navegador, de um site que não está na lista permitida.	Use um cliente MCP fora do navegador.

Testar a conexão com curl

Os clientes MCP fazem isso por você. Se quiser conferir a chave na mão, este pedido lista as ferramentas:

curl -X POST https://platform.festero.com.br/v1/mcp \
  -H "Authorization: Bearer fk_mcp_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"teste","version":"1"}}}}'

A resposta traz as 10 ferramentas. O servidor só aceita POST nesse endereço.

Versões em Markdown

Este portal também foi feito para ser lido por assistentes de IA, não só por pessoas:

• Toda página tem uma versão em Markdown, na mesma rota com .md no fim. Por exemplo, https://developers.festero.com.br/api/financeiro.md é a versão em Markdown de Financeiro, e https://developers.festero.com.br/mcp.md é esta página.
• /llms.txt é um índice de todas as páginas, com uma linha para cada, no formato do llmstxt.org. Entregue esse endereço a um assistente para ele descobrir a documentação inteira.
• O contrato da API está em /openapi.v1.json.
• No topo de cada página há três botões: Copiar como Markdown (copia o texto da página para a área de transferência), Ver em Markdown (abre a versão .md) e Perguntar ao Claude (abre o Claude já com um pedido para ler a versão .md daquela página).

Um bom pedido a um assistente que vai escrever a sua integração: "leia https://developers.festero.com.br/llms.txt e use a documentação para escrever um cliente que lista os orçamentos aprovados do mês".