> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectvets.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP (agentes de IA)

> Conectar Claude, Cursor e outros clientes MCP ao Flow

# MCP — integração com agentes de IA

O [Model Context Protocol](https://modelcontextprotocol.io) permite que um agente de IA consulte os dados do workspace no Flow. O cliente só cola a URL e a chave — o agente descobre sozinho as ferramentas disponíveis.

## Quando usar MCP

Use quando o cliente quer perguntar em linguagem natural (ex.: “quais leads estão na etapa X?”) via Claude, Cursor, ChatGPT ou outro app compatível com MCP.

## MCP vs API REST

ERP e sistemas que **gravam** dados devem usar a [API REST](/flow/api-reference/contacts). MCP é para **consulta via IA** (somente leitura na v1).

## Como configurar

1. Crie uma chave em **Integrações → Gerenciar chaves** com o scope `mcp:read` (pode combinar com outros scopes).
2. No app de IA, adicione um servidor MCP HTTP usando uma das URLs abaixo.
3. Envie o header `Authorization: Bearer flow_live_…` — o workspace é detectado pela chave (não precisa passar `workspace_id` na URL).

## URLs do servidor MCP

| Ambiente | URL                                                  |
| -------- | ---------------------------------------------------- |
| Produção | `https://api.connectvets.com.br/flow/v1/mcp`         |
| Sandbox  | `https://api-sandbox.connectvets.com.br/flow/v1/mcp` |
| Local    | `http://localhost:8090/api/mcp`                      |

Transport: Streamable HTTP (stateless).

## Exemplo no Cursor

Em **Settings → MCP**, adicione um servidor com configuração semelhante a esta (ajuste a URL do ambiente):

```json theme={null}
{
  "mcpServers": {
    "flow": {
      "url": "https://api.connectvets.com.br/flow/v1/mcp",
      "headers": {
        "Authorization": "Bearer flow_live_<seu_token>"
      }
    }
  }
}
```

## Exemplo no Claude / outros clientes HTTP

Clientes MCP com transporte HTTP (Streamable) usam um JSON parecido com:

```json theme={null}
{
  "mcpServers": {
    "flow": {
      "type": "http",
      "url": "https://api.connectvets.com.br/flow/v1/mcp",
      "headers": {
        "Authorization": "Bearer flow_live_<seu_token>"
      }
    }
  }
}
```

## Ferramentas disponíveis (somente leitura)

Depois de conectar, o agente lista e chama estas tools automaticamente, sempre limitadas ao workspace da chave:

| Tool                   | O que faz                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| `list_leads`           | Lista leads ativos — filtros opcionais: `search`, `funnel_id`, `stage_id`, `limit`, `offset` |
| `get_lead`             | Detalhe de um lead por `lead_id` (contato + etapa)                                           |
| `list_pipelines`       | Lista funis (pipelines) do workspace                                                         |
| `list_pipeline_stages` | Lista etapas de um funil (exige `funnel_id`)                                                 |
| `search_contacts`      | Busca contatos por nome, telefone, e-mail ou documento                                       |
| `list_calendar_events` | Lista eventos de calendário — filtros: `from`/`to` (RFC3339), `status`, `limit`, `offset`    |
| `list_agendas`         | Lista agendas (calendários) do workspace                                                     |

## Exemplos de perguntas para o agente

* “Liste os leads ativos do funil principal.”
* “Busque o contato com telefone 11999998888.”
* “Quais consultas estão agendadas esta semana?”
* “Mostre as etapas do funil X.”

## Limites importantes

<Warning>
  * A v1 do MCP é **somente leitura** — não cria nem altera leads/contatos/agenda.
  * A chave define o workspace: o cliente nunca escolhe outro tenant.
  * Workspace com billing inativo também bloqueia o MCP (igual à API REST).
</Warning>