# Instalar o AportaAI no Claude

O AportaAI é um servidor MCP: você conecta uma vez e passa a perguntar sobre
ações, FIIs e a sua carteira direto no Claude. Endereço do servidor:

```
https://aporta-ai.bifrostlabs.xyz/eve/v1/mcp
```

## Antes de começar

- Uma conta no Claude. Conectores personalizados dependem do seu plano; veja
  a disponibilidade em Configurações → Conectores.
- Acesso ao AportaAI. O cadastro é por **lista de espera**: peça acesso
  (botão **Pedir acesso** no site ou na tela de login), receba o convite por
  e-mail, crie a conta pelo botão **Accept invitation** e só então conecte.

## Claude Code (terminal)

1. Adicione o servidor. `--scope user` deixa o AportaAI disponível em todos os
   seus projetos; sem ele, só na pasta atual.

   ```
   claude mcp add --transport http --scope user aporta https://aporta-ai.bifrostlabs.xyz/eve/v1/mcp
   ```

2. Abra uma sessão do Claude Code e digite `/mcp`.
3. Escolha `aporta` → **Authenticate**. O navegador abre a página de login.
4. Entre (ou peça acesso na lista de espera) e autorize. Volte ao terminal.
5. Teste: `Qual o dividend yield do TAEE11?`

### Comandos /aporta:* (opcional)

Instale o plugin com comandos prontos, como `/aporta:carteira`,
`/aporta:ativo TAEE11` e `/aporta:config idioma en`:

```
/plugin marketplace add 0xPuncker/aporta-plugin
/plugin install aporta@aporta
```

Com o plugin, você não precisa digitar `/aporta:` para tudo: pergunte normalmente
(`como está minha carteira?`, `comprei 5 MXRF11 a R$ 9,15`) e o Claude leva a
pergunta ao AportaAI. `/aporta:news` traz as novidades do dia na B3, na CVM e no
Investidor10 sobre os ativos da sua carteira; ele também é chamado quando você
pede "novidades do mercado". As notícias vêm da busca na web do próprio Claude,
não do AportaAI; as maiores altas e baixas do pregão vêm da base da B3 do AportaAI.

Alertas da carteira (queda forte de uma posição ou da carteira, possível
grupamento, corte de rendimento de FII, Tesouro sem preço) aparecem no início da
primeira resposta depois que surgem, uma vez cada. `/aporta:alertas` lista os
atuais, inclusive os já vistos. Para receber no Telegram, peça "ativar alertas no
Telegram": o AportaAI devolve um link de uso único (15 minutos); abra e toque em
Iniciar. Chega uma mensagem por dia, depois do fechamento, só com alerta novo —
com ticker, preços e impacto em R$, que passam pelos servidores do Telegram.
`/parar` no chat desativa.

O plugin já traz o servidor. Se você fez o passo 1, remova a entrada manual
antes (`claude mcp remove aporta`), senão ele aparece duas vezes.

Depois, `/aporta:update` traz a versão publicada mais recente — reinicie o
Claude Code para ela valer. Os dados de mercado e o agente não dependem disso:
eles se atualizam sozinhos no servidor.

## Claude na web, no Desktop e no celular

1. Em claude.ai, abra **Configurações → Conectores**.
2. **Adicionar conector personalizado**. Nome: `AportaAI`. URL: o endereço acima.
3. Clique em **Conectar**. A página de login abre; entre e autorize.
4. Numa conversa, ative o AportaAI no menu de ferramentas e pergunte.

Conectores adicionados na web aparecem também no Claude Desktop e no app do
celular com a mesma conta.

## O que perguntar

- `Qual o dividend yield do TAEE11?`
- `O BTLG11 distribui mais do que gera de caixa?`
- `Crie minha carteira com 50 TAEE11 a R$ 35,00 e 10 BTLG11 a R$ 100,00`
- `Comprei 5 MXRF11 a R$ 9,15`
- `Como está minha carteira?`
- `Responda em inglês` · `Quero respostas detalhadas`

Nas tabelas, o nome de cada ativo é um link para a página dele no
Investidor10. No Claude Code o terminal mostra a URL inteira ao lado do nome e
a tabela fica larga; peça `sem links` e o AportaAI passa a escrever só o ticker.

## Problemas comuns

| O que aparece | O que fazer |
|---|---|
| Pede login de novo ou dá 401 | `/mcp` → `aporta` → **Authenticate** (no Claude Code) ou reconecte o conector (na web). |
| Login não passa da lista de espera | Seu acesso ainda não foi liberado. |
| "Cota diária do AportaAI atingida" | O limite diário por conta foi atingido; renova à meia-noite (UTC). |
| Pergunta pausada pedindo Aprovar ou Parar | A pergunta chegou ao limite de processamento. Aprovar continua; Parar encerra. |
| "Fora do escopo" | O AportaAI só responde sobre ações, FIIs, Fiagros, a sua carteira e o próprio serviço. |
| Erro 429 | Muitas requisições ao mesmo tempo; espere um minuto e tente de novo. |

## Atualizações

O servidor se atualiza sozinho: cada nova versão vale a partir da próxima
pergunta, sem nada a fazer no Claude. Só o plugin do Claude Code precisa de
`/plugin marketplace update aporta` e um reinício.

## Remover e apagar os seus dados

- Claude Code: `claude mcp remove aporta` (ou desinstale o plugin em `/plugin`).
- Claude na web: Configurações → Conectores → remova o AportaAI.
- Para apagar carteira, histórico e preferências do servidor, peça ao AportaAI
  `apague meu perfil` e confirme digitando `APAGAR`. Remover o conector não
  apaga os dados.

## Privacidade

A carteira fica no servidor do AportaAI, cifrada com uma chave própria por
conta. Para responder, a pergunta e os resultados das consultas passam pelo
modelo de IA (OpenAI; em caso de falha, OpenRouter). Para monitorar qualidade
e custo, perguntas, respostas e resultados das consultas - inclusive dados da
carteira - são registrados no Langfuse, serviço de observabilidade hospedado
nos EUA, associados a um identificador anônimo da conta. O login é feito pelo
Clerk; o AportaAI não vê a sua senha.

> O AportaAI é uma ferramenta de estudo sobre dados públicos da CVM e da B3.
> Não é recomendação de investimento nem relatório de análise (Resolução CVM
> 20/2021) e não considera o seu perfil de investidor.