# 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 de uma conversa com um assistente de IA conectado ao servidor MCP (valores fictícios)**

- Pergunta: Quais recebíveis estão vencidos?
- Ferramenta MCP chamada: `list_receivables` com `{ "status": "overdue" }`
- Resposta: 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](https://developers.festero.com.br/autenticacao.md)). | 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](https://developers.festero.com.br/autenticacao.md)).
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.

> **Atenção**: 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](https://developers.festero.com.br/limites.md) 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

```bash
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:

```json
{
  "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_...`.

> **Informação**: 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](https://developers.festero.com.br/api/crm.md), [Visitas](https://developers.festero.com.br/api/visitas.md), [Eventos](https://developers.festero.com.br/api/eventos.md), [Orçamentos](https://developers.festero.com.br/api/orcamentos.md) e [Financeiro](https://developers.festero.com.br/api/financeiro.md).

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.

> **Dica**: 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:

```bash
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](https://developers.festero.com.br/api/financeiro.md), e `https://developers.festero.com.br/mcp.md` é esta página.
- **[`/llms.txt`](https://developers.festero.com.br/llms.txt)** é um índice de todas as páginas, com uma linha para cada, no formato do [llmstxt.org](https://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`](https://developers.festero.com.br/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".