# Servidor MCP

> Ligue o Claude, o Cursor, o Codex ou qualquer cliente MCP aos registos de conformidade de um restaurante com um URL e a sua chave de API.

Source: https://developers.backresto.com/pt/docs/mcp

A BackResto tem um servidor **Model Context Protocol** em
`https://api.backresto.com/mcp`. Ligue-lhe a sua ferramenta de IA com a sua
chave de API e pode fazer perguntas sobre os registos de um restaurante na
própria interface da ferramenta: sem código, nada para instalar do nosso lado,
nada para alojar do seu.

Lê através da mesma API de Parceiros que tudo o resto, com a mesma chave.
**Não consegue ver nada que a chave não pudesse já ver**: as concessões por
restaurante e por scope são aplicadas pela API, não pela ferramenta que ligar.

## Ligue a sua ferramenta

Primeiro precisa de uma chave; veja [Obter uma chave](https://developers.backresto.com/pt/docs/access). Depois,
escolha a sua ferramenta:

### Claude

1. **Adicionar um conector personalizado**: No Claude, na aplicação de desktop ou em claude.ai, abra Personalizar, depois Conectores, e clique em Adicionar conector personalizado. Num plano Team ou Enterprise, um proprietário adiciona-o primeiro uma vez nas definições da organização.

2. **Dar-lhe um nome e colar o endereço**: Chame-lhe BackResto e cole este URL. Em Autenticação e Cliente OAuth, o Claude deteta o nosso servidor e pré-seleciona Iniciar sessão agora e Registar automaticamente: mantenha essas duas opções. Não introduza ID de cliente nem segredo. Depois clique em Adicionar.

```
https://api.backresto.com/mcp
```

3. **Ligar com a sua chave**: Clique em Ligar. Abre-se uma página da BackResto: cole a sua chave, que começa por brp_, e clique em Ligar. O Claude volta com o conector ativo e as suas cinco ferramentas.

4. **Pronto**: Pergunte pelos registos do restaurante por palavras normais. A chave já sabe qual é o seu restaurante.

### Claude Code

1. **Registar o servidor**: Abra um terminal e execute este comando, com a sua chave em vez de brp_YOUR_KEY.

```sh
claude mcp add --transport http --scope user backresto \
  https://api.backresto.com/mcp \
  --header "Authorization: Bearer brp_YOUR_KEY"
```

2. **Verificar a ligação**: Inicie o Claude Code e escreva /mcp. backresto aparece como ligado, com cinco ferramentas.

3. **Pronto**: Pergunte pelos registos do restaurante por palavras normais. A chave já sabe qual é o seu restaurante.

### Cursor

1. **Abrir as definições de MCP**: No Cursor, vá a Settings, depois Tools & MCP, e clique em New MCP Server. Isso abre o mcp.json.

2. **Adicionar o servidor**: Cole isto no mcp.json, com a sua chave em vez de brp_YOUR_KEY. O servidor aparece na lista com cinco ferramentas.

```json
{
  "mcpServers": {
    "backresto": {
      "type": "http",
      "url": "https://api.backresto.com/mcp",
      "headers": {
        "Authorization": "Bearer brp_YOUR_KEY"
      }
    }
  }
}
```

3. **Pronto**: Pergunte pelos registos do restaurante por palavras normais. A chave já sabe qual é o seu restaurante.

### Codex

1. **Pôr a chave no ambiente**: O Codex lê um token bearer de uma variável de ambiente em vez do seu ficheiro de configuração. Adicione esta linha ao seu perfil da shell, com a sua chave em vez de brp_YOUR_KEY.

```sh
export BACKRESTO_API_KEY="brp_YOUR_KEY"
```

2. **Registar o servidor**: Depois execute isto uma vez. O Codex envia o valor da variável como cabeçalho Authorization.

```sh
codex mcp add backresto \
  --url https://api.backresto.com/mcp \
  --bearer-token-env-var BACKRESTO_API_KEY
```

3. **Pronto**: Pergunte pelos registos do restaurante por palavras normais. A chave já sabe qual é o seu restaurante.

### Outra

1. **Abrir as definições de MCP da sua ferramenta**: Encontre a secção de MCP ou de integrações e adicione um servidor remoto com Streamable HTTP. Se a sua ferramenta só pedir um URL, abre uma página da BackResto onde cola a chave, e o cabeçalho deixa de ser preciso.

2. **Introduzir o endereço**: Este é o URL do servidor.

```
https://api.backresto.com/mcp
```

3. **Adicionar a chave como cabeçalho**: Envie-a em cada pedido como cabeçalho Authorization.

```
Authorization: Bearer brp_YOUR_KEY
```

4. **Pronto**: Pergunte pelos registos do restaurante por palavras normais. A chave já sabe qual é o seu restaurante.

## As ferramentas

Cinco ferramentas: uma que encontra o restaurante, e quatro que leem as suas
[coleções](https://developers.backresto.com/pt/docs/collections).

| Ferramenta | O que faz |
| --- | --- |
| `backresto_list_restaurants` | Lista os restaurantes que a chave alcança, com os seus scopes em cada um. |
| `backresto_list_collections` | Lista as coleções que foram concedidas a esta chave, com o scope que abriu cada uma. É a primeira chamada certa quando não sabe o que a chave alcança. |
| `backresto_list_records` | Lê uma página de registos de uma coleção, tombstones incluídos. Recebe `collection`, e opcionalmente `limit` (1-100, 50 por omissão) e `cursor`. |
| `backresto_get_record` | Obtém um registo pela `collection` e pelo `recordId`. |
| `backresto_list_record_assets` | Lista os ficheiros associados a um registo (`cleaning-task-pictures`, `delivery-pictures`, `traceability-labels` ou `drive-files`) como URL assinados, e mostra as fotografias ao modelo como imagens que ele pode ver. |

As entregas são duas dessas coleções, `deliveries` e `delivery-pictures`, lidas
com as mesmas ferramentas que tudo o resto. Veja [Entregas](https://developers.backresto.com/pt/docs/deliveries)
para o que significam os seus campos.

`restaurantId` é opcional em todo o lado. Se o omitir, é usado o restaurante da
chave: um restaurante com uma só chave nunca precisa de conhecer o seu
identificador. Só uma chave que alcança vários restaurantes tem de escolher, e o
erro indica as opções.

As cinco estão declaradas como só de leitura e idempotentes, pelo que um cliente
bem comportado não lhe pede autorização a cada chamada, como faz com uma
ferramenta que escreve.

Dois limites práticos. As fotografias são incorporadas para o modelo até **dez
imagens e cerca de 7,5 MB** por chamada a `backresto_list_record_assets`; o que passar disso continua a aparecer
no resumo, com o seu URL e a razão por que não foi mostrado. E todo o endpoint
partilha o [orçamento](https://developers.backresto.com/pt/docs/rate-limits) da API de Parceiros de 300 pedidos por
minuto por chave: uma chamada de ferramenta é um pedido, um número de que uma
conversa nunca se aproxima e um ciclo sim.

## Proteger a chave

A chave é a totalidade do seu acesso, e a configuração de um cliente MCP é um
ficheiro comum num portátil.

- **Nunca faça commit desse ficheiro.** Se a sua ferramenta guarda a
  configuração num repositório, faça referência a uma variável de ambiente ou a
  um cofre de segredos do sistema, como faz a configuração do Codex acima.
- **Dê a cada máquina a sua própria chave.** Uma chave por portátil significa
  que um portátil perdido custa uma revogação, não uma rotação em todas as suas
  integrações.
- **Pergunte-nos quando uma chave foi usada pela última vez** se suspeitar que
  ainda há uma cópia ativa algures. Vemos a última autenticação de cada chave,
  e uma revogação é o mesmo email.

## Ligar apenas com o URL

O Claude (aplicação de desktop e claude.ai), o ChatGPT e outras ferramentas que
só pedem o URL de um servidor ligam-se por OAuth: registam-se sozinhas na
BackResto e depois abrem uma página da BackResto onde cola a sua chave uma vez.
Nada para instalar, nenhum ficheiro de configuração. A ferramenta guarda a
chave e envia-a por si: chega exatamente ao que a chave chega, e revogar a
chave desliga-a.

Ainda não existe início de sessão com uma conta BackResto: a chave continua a
ser a credencial. Se é isso que o separa de uma integração, diga-nos: sobe na
lista.

## Em que é bom

Em concreto, com as ferramentas ligadas, um responsável de operações pode
perguntar:

- *«Que entregas foram recusadas no mês passado, e porquê?»*
- *«Mostra-me todas as entregas de frango acima de 4 °C neste trimestre.»*
- *«Mostra-me as fotos da entrega recusada na terça-feira: vê-se o dano?»*
- *«Que frigoríficos saíram de intervalo mais vezes, e em que zona?»*
- *«Os ciclos de arrefecimento desceram todos a tempo na semana passada?»*
- *«Que tarefas de limpeza ficaram por fazer, e quais não têm fotografia?»*

As três primeiras leem as coleções `deliveries` e `delivery-pictures`, as
restantes leem outras [coleções](https://developers.backresto.com/pt/docs/collections), e todas elas apenas o que
foi concedido à sua chave. As respostas vêm dos mesmos registos que um inspetor leria, através das
mesmas concessões que o restaurante emitiu.

A um modelo que lê coleções deve ser dito o que está a ler: um snapshot
daquilo que a API recebeu, não um histórico com completude garantida. Se puser
isto à frente de um cliente, ponha essa frase ao lado.