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

# Avantti + IA (MCP e LLMs)

> Conecte sua infraestrutura financeira a modelos de IA, agentes autônomos e aplicações via MCP

> Infraestrutura financeira preparada para IA, automações inteligentes, MCPs e Large Language Models.

A Avantti AI conecta pagamentos, contas, eventos e operações financeiras diretamente com agentes inteligentes, automações e aplicações baseadas em LLMs. Construa produtos AI-native com acesso seguro e estruturado à infraestrutura financeira da Avantti.

## Visão geral

<CardGroup cols={2}>
  <Card title="Integrar LLMs" icon="brain-circuit">
    Conecte modelos de linguagem diretamente às operações financeiras.
  </Card>

  <Card title="Agentes autônomos" icon="bot">
    Crie agentes que executam pagamentos e consultas de forma independente.
  </Card>

  <Card title="Automação via linguagem natural" icon="zap">
    Execute ações financeiras descrevendo o que precisa em texto livre.
  </Card>

  <Card title="MCP nativo" icon="plug">
    Use o Model Context Protocol para integrar com Claude, ChatGPT, Cursor e mais.
  </Card>
</CardGroup>

## O que é MCP

MCP (Model Context Protocol) é um protocolo aberto para conectar modelos de IA com ferramentas externas, APIs e sistemas. Com MCP, modelos conseguem ler dados, executar ações, consumir APIs, operar sistemas financeiros e interagir com contexto em tempo real.

## Avantti MCP

O Avantti MCP fornece acesso estruturado à infraestrutura financeira da Avantti para Claude, ChatGPT, Cursor, Windsurf, VSCode AI, agentes personalizados e aplicações AI-native.

### Capacidades

| Recurso       | Descrição            |
| ------------- | -------------------- |
| Payments      | Criar pagamentos     |
| Customers     | Gerenciar clientes   |
| Balance       | Consultar saldo      |
| Webhooks      | Consumir eventos     |
| Refunds       | Criar reembolsos     |
| Accounts      | Gerenciar contas     |
| Analytics     | Métricas financeiras |
| Subscriptions | Assinaturas          |

### Instalação

<CodeGroup>
  ```bash NPX theme={null}
  npx @avantti/mcp
  ```

  ```bash Docker theme={null}
  docker run avantti/mcp
  ```

  ```json Configuração manual theme={null}
  {
    "mcpServers": {
      "avantti": {
        "command": "npx",
        "args": ["@avantti/mcp"],
        "env": {
          "AVANTTI_API_KEY": "sk_test_xxxxx"
        }
      }
    }
  }
  ```
</CodeGroup>

### Configuração por cliente

<Tabs>
  <Tab title="Claude Desktop">
    Localize o arquivo de configuração de acordo com seu sistema operacional:

    **macOS**

    ```txt theme={null}
    ~/Library/Application Support/Claude/claude_desktop_config.json
    ```

    **Windows**

    ```txt theme={null}
    %APPDATA%\Claude\claude_desktop_config.json
    ```

    Em seguida, adicione:

    ```json theme={null}
    {
      "mcpServers": {
        "avantti": {
          "command": "npx",
          "args": ["@avantti/mcp"],
          "env": {
            "AVANTTI_API_KEY": "sk_test_xxxxx"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    ```json theme={null}
    {
      "mcpServers": {
        "avantti": {
          "command": "npx",
          "args": ["@avantti/mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    ```json theme={null}
    {
      "mcpServers": {
        "avantti": {
          "command": "npx",
          "args": ["@avantti/mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Ferramentas disponíveis

| Tool                   | Descrição         |
| ---------------------- | ----------------- |
| `payments.create`      | Criar pagamento   |
| `payments.get`         | Buscar pagamento  |
| `payments.list`        | Listar pagamentos |
| `customers.create`     | Criar cliente     |
| `customers.get`        | Buscar cliente    |
| `refunds.create`       | Criar reembolso   |
| `balance.get`          | Consultar saldo   |
| `subscriptions.create` | Criar assinatura  |

### Exemplos de uso

<Tabs>
  <Tab title="Claude">
    **Prompt**

    ```txt theme={null}
    Crie um pagamento PIX de R$50 para João Silva.
    ```

    **Resultado**

    O modelo irá:

    1. Interpretar o pedido
    2. Executar a tool financeira
    3. Criar o pagamento
    4. Retornar QR Code e detalhes
  </Tab>

  <Tab title="ChatGPT">
    **Prompt**

    ```txt theme={null}
    Liste os pagamentos aprovados hoje.
    ```

    **Resultado**

    A IA irá consultar a API da Avantti e retornar os pagamentos filtrados.
  </Tab>

  <Tab title="Agente autônomo">
    ```ts theme={null}
    const response = await agent.run(
      "Crie uma cobrança PIX de R$100"
    )
    ```
  </Tab>
</Tabs>

## SDK de IA (Node.js)

<Steps>
  <Step title="Instale o pacote">
    ```bash theme={null}
    npm install @avantti/ai
    ```
  </Step>

  <Step title="Inicialize o cliente">
    ```ts theme={null}
    import { AvanttiAI } from "@avantti/ai"

    const ai = new AvanttiAI({
      apiKey: process.env.AVANTTI_API_KEY
    })
    ```
  </Step>

  <Step title="Crie um agente">
    ```ts theme={null}
    const agent = ai.agent({
      tools: ["payments", "customers"]
    })
    ```
  </Step>

  <Step title="Execute uma ação">
    ```ts theme={null}
    const response = await agent.run(
      "Crie um pagamento PIX de R$50"
    )
    ```
  </Step>
</Steps>

## Tool calling

A Avantti AI suporta tool calling compatível com OpenAI, Anthropic, Gemini, Groq, DeepSeek e Ollama.

<CodeGroup>
  ```ts OpenAI theme={null}
  import OpenAI from "openai"

  const openai = new OpenAI()

  const completion = await openai.chat.completions.create({
    model: "gpt-4.1",
    tools: [
      {
        type: "function",
        function: {
          name: "create_payment",
          description: "Cria pagamento PIX"
        }
      }
    ],
    messages: [
      {
        role: "user",
        content: "Crie um PIX de R$50"
      }
    ]
  })
  ```

  ```ts Anthropic theme={null}
  const response = await anthropic.messages.create({
    model: "claude-sonnet-4",
    tools: [
      {
        name: "payments_create",
        description: "Cria pagamento"
      }
    ]
  })
  ```

  ```ts LangChain theme={null}
  import { AvanttiTool } from "@avantti/ai/langchain"

  const tools = [
    new AvanttiTool()
  ]
  ```

  ```ts Vercel AI SDK theme={null}
  import { avanttiTools } from "@avantti/ai/vercel"

  const tools = avanttiTools()
  ```
</CodeGroup>

## Segurança

A Avantti AI foi construída com foco em segurança.

<CardGroup cols={2}>
  <Card title="Escopo de permissões" icon="key">
    Controle granular sobre quais ações cada integração pode executar.
  </Card>

  <Card title="Isolamento por workspace" icon="box">
    Cada workspace opera de forma isolada, sem vazamento de contexto.
  </Card>

  <Card title="Validação de tool calls" icon="shield-check">
    Toda chamada de ferramenta é validada antes da execução.
  </Card>

  <Card title="Rate limiting" icon="gauge">
    Limites de requisição protegem contra uso abusivo.
  </Card>

  <Card title="Logs auditáveis" icon="file-text">
    Todas as ações de IA ficam registradas para auditoria.
  </Card>

  <Card title="Assinaturas criptográficas" icon="lock">
    Requisições críticas são assinadas criptograficamente.
  </Card>
</CardGroup>

### Permissões

```json theme={null}
{
  "permissions": {
    "payments:create": true,
    "refunds:create": false
  }
}
```

### Ambientes

<CodeGroup>
  ```env Sandbox theme={null}
  AVANTTI_ENV=sandbox
  ```

  ```env Produção theme={null}
  AVANTTI_ENV=production
  ```
</CodeGroup>

## Eventos em tempo real

A Avantti AI pode consumir eventos em tempo real:

```ts theme={null}
ai.events.on("payment.approved", (event) => {
  console.log(event)
})
```

### Automação

Um fluxo automático típico:

```txt theme={null}
Cliente paga → webhook → IA interpreta → ação automática
```

## Casos de uso

<CardGroup cols={2}>
  <Card title="Atendimento financeiro" icon="headset">
    Segunda via automática, consulta de pagamentos, status de cobranças e reembolsos automáticos.
  </Card>

  <Card title="Operações" icon="settings">
    Conciliação, monitoramento, alertas inteligentes e análise de fraude.
  </Card>

  <Card title="Checkout AI-native" icon="shopping-cart">
    Cobranças por linguagem natural, assistentes de compra e conversational commerce.
  </Card>

  <Card title="ERP AI" icon="building-2">
    Integrações financeiras inteligentes, operações automatizadas e fluxos autônomos.
  </Card>
</CardGroup>

## Estrutura de resposta

```json theme={null}
{
  "success": true,
  "data": {
    "id": "pay_123456",
    "status": "approved"
  }
}
```

## Logs e depuração

Para ativar o modo debug:

```env theme={null}
AVANTTI_DEBUG=true
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP não conecta">
    Verifique:

    * Node.js instalado
    * API Key válida
    * Variáveis de ambiente
    * Firewall
    * Configuração JSON
  </Accordion>

  <Accordion title="Erro de autenticação">
    ```txt theme={null}
    Invalid API Key
    ```

    Confirme:

    * Ambiente correto
    * Token ativo
    * Permissões habilitadas
  </Accordion>
</AccordionGroup>

## Performance

O MCP da Avantti foi otimizado para baixa latência, tool calling rápido, streaming, alta concorrência e execução paralela.

### Compatibilidade

| Plataforma     | Compatível |
| -------------- | ---------- |
| Claude Desktop | Sim        |
| Cursor         | Sim        |
| Windsurf       | Sim        |
| VSCode AI      | Sim        |
| OpenAI SDK     | Sim        |
| LangChain      | Sim        |
| Vercel AI SDK  | Sim        |

## Boas práticas

* Utilize sandbox durante o desenvolvimento
* Restrinja permissões ao mínimo necessário
* Faça validação de inputs
* Monitore tool calls
* Utilize logs auditáveis

## Recursos relacionados

<CardGroup cols={2}>
  <Card title="Referência da API" icon="code" href="/pages/reference/introduction">
    Explore todos os endpoints disponíveis.
  </Card>

  <Card title="SDKs" icon="package" href="/Sdk">
    Bibliotecas oficiais para integração.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli">
    Gerencie sua conta pela linha de comando.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/pages/webhook/overview">
    Receba eventos em tempo real.
  </Card>
</CardGroup>

Você também pode consultar a página de Status e o Changelog para acompanhar atualizações da plataforma.

## Suporte

Caso precise de ajuda, entre em contato:

<CardGroup cols={2}>
  <Card title="E-mail" icon="mail" href="mailto:suporte@avanttifinance.com">
    [suporte@avanttifinance.com](mailto:suporte@avanttifinance.com)
  </Card>

  <Card title="Comunidade" icon="message-circle">
    Participe do nosso Discord da comunidade ou abra uma issue no GitHub.
  </Card>
</CardGroup>

***

A Avantti AI foi construída para conectar infraestrutura financeira moderna com a próxima geração de aplicações baseadas em IA.