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

# MCP (Claude, ChatGPT, Cursor)

> Conecte um assistente de IA aos dados da sua empresa na Velan pelo Model Context Protocol, com autorização OAuth ou chave de API. Somente leitura.

O servidor MCP da Velan deixa um assistente de IA consultar **produtos, ofertas, pedidos, assinaturas, compradores e resumo financeiro** da sua empresa em linguagem natural: "quantas vendas pagas tive esta semana por produto?", "quais assinaturas renovam nos próximos 15 dias?", "o cliente [joao@exemplo.com](mailto:joao@exemplo.com) pagou?".

**URL do servidor:** `https://mcp.velan.app/mcp`

<Note>
  Todo o acesso é **somente leitura** e fica restrito à empresa autorizada. O MCP não cria, altera nem estorna nada, e não enxerga integrações nem membros da equipe.
</Note>

## Conectar

### Claude Code

```bash theme={null}
claude mcp add --transport http velan https://mcp.velan.app/mcp
```

Na primeira chamada o Claude Code abre o navegador: você entra na Velan, confere a empresa e clica em **Autorizar**. Pronto.

Ou no arquivo `.mcp.json` do projeto:

```json theme={null}
{
  "mcpServers": {
    "velan": { "type": "http", "url": "https://mcp.velan.app/mcp" }
  }
}
```

### Claude.ai, ChatGPT, Cursor e outros

Adicione um conector/servidor MCP remoto com a URL `https://mcp.velan.app/mcp`. O cliente descobre o OAuth sozinho (RFC 9728) e abre a tela de autorização da Velan.

### Com chave de API (sem OAuth)

Para scripts e clientes que aceitam cabeçalho fixo, gere uma chave em **Configurações → Empresa → Chaves de API** e use:

```json theme={null}
{
  "mcpServers": {
    "velan": {
      "type": "http",
      "url": "https://mcp.velan.app/mcp",
      "headers": { "Authorization": "Bearer vk_live_..." }
    }
  }
}
```

A mesma chave vale para a [API REST](/integrations/api) (`https://api.velan.app/v1`, só leitura).

## O que você pode perguntar

Depois de conectar, é só perguntar em português. Alguns exemplos que o assistente responde com os dados da sua empresa:

**Vendas e faturamento**

* "Quanto vendi este mês? E em setembro, por produto?"
* "Qual forma de pagamento mais converte nos últimos 30 dias?"
* "Quantas vendas pagas tive por dia na última semana?"
* "Quantos estornos tive no período e quanto representaram?"

**Pedidos**

* "O cliente [joao@exemplo.com](mailto:joao@exemplo.com) pagou? Quando e como?"
* "Liste os pedidos pendentes de hoje."
* "Quais pedidos falharam no cartão esta semana e por qual motivo?"
* "Quantos PIX expiraram sem pagamento no mês?"
* "Detalhe o pedido 33314cb8: cobranças, bumps, taxas e cupom."
* "Quais vendas vieram de utm\_source=instagram em setembro?"

**Assinaturas**

* "Quantas assinaturas ativas tenho? Quantas em atraso?"
* "Quem renova nos próximos 15 dias e quanto entra?"
* "Quais assinaturas cancelaram este mês?"
* "Mostre o histórico de cobranças da assinatura da Maria."

**A receber**

* "O que tenho a receber nos próximos 30 dias, entre renovações e boletos em aberto?"

**Produtos e ofertas**

* "Quais produtos estão ativos e quantas ofertas cada um tem?"
* "Qual o preço e o link de checkout das ofertas do produto X?"

**Compradores**

* "O que o CPF 123.456.789-00 já comprou comigo?"
* "Quais compradores da oferta A também assinam o plano B?"

O assistente combina as ferramentas quando precisa: para a última pergunta, ele lista os dois grupos e cruza por e-mail.

<Note>
  **Ainda fora do alcance:** carrinhos abandonados e leads, afiliados e comissões, cupons, entregas de webhooks, ingressos e check-in de eventos, e qualquer ação, como estornar ou criar cupom. Se precisar de algum desses, fale com o suporte.
</Note>

## Mais de uma empresa

Se você administra várias empresas na Velan, a tela de autorização lista todas as que você é dono ou administrador; desmarque as que não quiser expor. Uma única conexão passa a enxergar todas as marcadas:

* Sem indicar empresa, as respostas são da empresa que estava selecionada ao autorizar (a **principal**).
* Diga o nome ou o código da empresa na pergunta ("quanto vendi na Loja Dois este mês?") e o assistente usa o parâmetro `company`.
* "Quanto vendi em todas as empresas?" faz o assistente listar as empresas com `list_companies` e somar.

Chaves de API criadas em Configurações → Empresa também podem incluir outras empresas suas.

## Ferramentas disponíveis

Todas aceitam o parâmetro opcional `company` (código ou nome).

| Ferramenta | O que faz |
| - | - |
| `list_companies` | Empresas que esta conexão pode consultar, a principal primeiro. |
| `list_products` / `get_product` | Produtos e suas ofertas (preço, formas de pagamento, link do checkout). |
| `list_orders` / `get_order` | Pedidos com filtros de status, produto, oferta, e-mail e período; detalhe com cobranças, bumps e motivo de recusa. |
| `list_subscriptions` / `get_subscription` | Assinaturas com status, próxima cobrança e histórico de ciclos. |
| `sales_summary` | Vendas pagas no período: quantidade, bruto, líquido, estornos; agrupado por dia, produto ou forma de pagamento. |
| `receivables` | A receber nos próximos N dias: renovações previstas e PIX/boletos em aberto. |
| `search_customer` | Comprador por e-mail ou CPF/CNPJ, com pedidos e assinaturas. |

Valores vêm em reais como texto decimal (`"297.00"`); datas em ISO 8601 (UTC). Códigos de pedido, produto e assinatura são UUIDs; códigos de oferta e plano têm 8 caracteres.

## Autorização e revogação

* Só o **proprietário ou um administrador** da empresa pode autorizar um aplicativo.
* Cada autorização aparece em **Configurações → Empresa → Chaves de API** como uma chave do tipo OAuth. Revogar ali encerra o acesso na hora.
* Tokens de acesso duram 24 horas e são renovados automaticamente pelo cliente (refresh token de 90 dias).

## Para desenvolvedores

O servidor segue a especificação MCP 2025-06-18 sobre Streamable HTTP (respostas JSON, sem SSE) e OAuth 2.1 com PKCE (S256), registro dinâmico de clientes (RFC 7591) e metadados em `/.well-known/oauth-authorization-server` e `/.well-known/oauth-protected-resource`. Só clientes públicos são aceitos; `redirect_uri` precisa ser `https://` ou loopback.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.