# Servidor MCP

A **Model Context Protocol (MCP) server** da Pluggy permite que qualquer agente de IA leia a documentação, guias, referência da API, changelog, receitas e perguntas e respostas curadas da Pluggy diretamente em tempo de execução. Em vez de adivinhar a partir de dados de treinamento desatualizados, seu agente responde a perguntas e escreve código de integração baseado na documentação **live** — com citações.

O servidor está hospedado em:

```
https://mcp.pluggy.ai/mcp
```

É um servidor HTTP remoto: **sem instalação, sem chave de API.** Aponte qualquer cliente compatível com MCP para essa URL e funcionará.

O servidor agora vive em seu próprio endereço, então permanece o mesmo mesmo que o site da documentação se mova depois — `https://mcp.pluggy.ai/mcp` é a URL a ser usada a partir de agora. A anterior, `https://v2.docs.pluggy.ai/api/mcp`, continua funcionando, então qualquer coisa que você já configurou está bem como está.

**Uma URL, login opcional — o mesmo servidor para todos:**

- **Sem fazer login** → as ferramentas de documentação pública (docs, referência da API, changelog, receitas, perguntas e respostas).
- **Logado com sua conta do dashboard da Pluggy** → o acima **mais suas ferramentas de portal de desenvolvedor** — suas equipes, aplicações, conectores, itens e uso — limitados à sua equipe. O login é opcional; use anonimamente para docs, ou conecte-se aos seus dados.

<Callout variant="info" title="Habilidades vs. MCP">
O servidor MCP dá a um agente acesso ao vivo à documentação da Pluggy em tempo de execução. [Habilidades do Agente](/docs/developer-tools/ai-skills) dão ao agente o conhecimento — os padrões e melhores práticas — para construir com a Pluggy. Eles funcionam de forma independente, e ainda melhor juntos — a página [Construir com IA](/build-with-ai) configura ambos, além de llms.txt, em um só lugar.
</Callout>

## O que você pode fazer com isso

Uma vez conectado, peça ao seu agente para construir com a Pluggy e ele puxará a resposta exata e atual em vez de alucinar:

- **"Como eu crio um connect token e abro o Connect Widget?"** → passos fundamentados nos guias ao vivo.
- **"Mostre-me os detalhes do endpoint `createItem`."** → método, caminho, parâmetros e esquemas diretamente da especificação OpenAPI.
- **"O que mudou na última versão para webhooks?"** → a entrada real do changelog, não uma suposição.
- **"Por que meu item está preso em `WAITING_USER_INPUT`?"** → a pergunta e resposta curadas, verificadas por humanos, que responderam isso antes.
- **"Escreva o código para listar as transações de um usuário com paginação."** → código de integração que corresponde à API atual.

Como ele lê o mesmo conteúdo publicado neste site, as respostas permanecem corretas à medida que a documentação evolui — você nunca reensina seu agente.

## Ferramentas disponíveis

| Ferramenta         | O que faz                                                                                              |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `query`            | Faça uma pergunta em linguagem natural e obtenha uma resposta gerada **com citações**, combinando docs, changelog, receitas e referência da API |
| `search_docs`      | Pesquise os guias de documentação (conceitos, quickstart, integração) com trechos classificados por relevância        |
| `search_qa`        | Pesquise as perguntas e respostas curadas, verificadas por humanos — a fonte de maior confiança para perguntas do tipo "como faço / por que X acontece" |
| `search_changelog` | Pesquise o changelog — notas de lançamento, mudanças significativas, notas de migração                                   |
| `search_recipes`   | Pesquise as receitas — padrões de integração, exemplos de código                                        |
| `get_guide`        | Recupere o conteúdo completo de um único guia de documentação por slug e localidade                              |
| `list_guides`      | Liste todos os guias de documentação (slug, título, descrição, categoria) para uma localidade                           |
| `get_api_endpoint` | Obtenha detalhes completos de um endpoint da API por `operationId` — método, caminho, parâmetros, corpo da solicitação, respostas  |
| `list_endpoints`   | Liste todos os endpoints da API Pluggy da especificação OpenAPI, opcionalmente filtrados por tag                           |
| `submit_feedback`  | Envie uma observação concreta sobre uma resposta incorreta, informação faltante, orientação confusa ou um problema de ferramenta para revisão pela Pluggy |

## Conecte-o à sua ferramenta

Escolha seu agente abaixo. Em todos os lugares que você vê, a URL do servidor é a mesma: `https://mcp.pluggy.ai/mcp`.

### Claude Code

```bash
claude mcp add --transport http pluggy-docs https://mcp.pluggy.ai/mcp
```

Adicione `-s user` para torná-lo disponível em todos os projetos: `claude mcp add -s user --transport http pluggy-docs https://mcp.pluggy.ai/mcp`.

### Claude Desktop

**Configurações → Conectores → Adicionar conector personalizado**, nomeie-o como `Pluggy Docs`, e cole `https://mcp.pluggy.ai/mcp`. Ou edite `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pluggy-docs": {
      "type": "http",
      "url": "https://mcp.pluggy.ai/mcp"
    }
  }
}
```

### ChatGPT (OpenAI)

Em **Configurações → Conectores → Avançado → Modo desenvolvedor**, adicione um conector com a URL `https://mcp.pluggy.ai/mcp`. (Conectores MCP remotos personalizados estão disponíveis no ChatGPT Plus/Pro/Business/Enterprise.) Em um chat, ative o conector `Pluggy Docs` e pergunte.

### OpenAI Codex CLI

Adicione a `~/.codex/config.toml`:

```toml
[mcp_servers.pluggy-docs]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.pluggy.ai/mcp"]
```

Codex se comunica com servidores MCP locais (stdio), então `mcp-remote` faz a ponte para o servidor HTTP hospedado.

### Cursor

Adicione a `~/.cursor/mcp.json` (global) ou `.cursor/mcp.json` (por projeto):

```json
{
  "mcpServers": {
    "pluggy-docs": {
      "url": "https://mcp.pluggy.ai/mcp"
    }
  }
}
```

### VS Code (modo agente do GitHub Copilot)

Um comando:

```bash
code --add-mcp '{"name":"pluggy-docs","type":"http","url":"https://mcp.pluggy.ai/mcp"}'
```

Ou crie `.vscode/mcp.json` em seu espaço de trabalho:

```json
{
  "servers": {
    "pluggy-docs": {
      "type": "http",
      "url": "https://mcp.pluggy.ai/mcp"
    }
  }
}
```

### Windsurf

Adicione a `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "pluggy-docs": {
      "serverUrl": "https://mcp.pluggy.ai/mcp"
    }
  }
}
```

### Gemini CLI

Adicione a `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "pluggy-docs": {
      "httpUrl": "https://mcp.pluggy.ai/mcp"
    }
  }
}
```

### Zed

Adicione ao seu `settings.json` do Zed:

```json
{
  "context_servers": {
    "pluggy-docs": {
      "command": {
        "path": "npx",
        "args": ["-y", "mcp-remote", "https://mcp.pluggy.ai/mcp"]
      }
    }
  }
}
```

### Qualquer outro cliente MCP

Se seu cliente só suporta servidores locais (stdio), faça a ponte para o hospedado com [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```bash
npx -y mcp-remote https://mcp.pluggy.ai/mcp
```

Clientes que suportam servidores **Streamable HTTP** remotos podem usar a URL diretamente.

## Teste sua configuração

Inicie um novo chat com seu agente e tente:

```
Usando os docs MCP da Pluggy, como eu crio um connect token e abro o Connect Widget?
```

ou

```
Liste os endpoints da API Pluggy para Itens e mostre-me os detalhes do createItem.
```

O agente deve chamar as ferramentas MCP e responder com citações da documentação ao vivo. Se nada acontecer, reinicie o cliente após adicionar o servidor e confirme se a URL é exatamente `https://mcp.pluggy.ai/mcp`.

## O que ele expõe

O servidor cobre tudo publicado neste site:

- **Guias de documentação** — conceitos, quickstart e guias de integração (EN e PT)
- **Referência da API** — cada endpoint da especificação OpenAPI, com parâmetros e esquemas
- **Changelog** — notas de lançamento, mudanças significativas e notas de migração
- **Receitas** — padrões de integração passo a passo e exemplos de código
- **Perguntas e respostas curadas** — perguntas reais de suporte respondidas e verificadas pela equipe da Pluggy

**Logado** (sua conta do dashboard da Pluggy), o mesmo servidor também expõe seu **portal de desenvolvedor**, limitado à sua equipe: liste suas equipes e aplicações, conectores, itens e estatísticas de uso. Seu token é validado e usado apenas para acessar os dados da sua própria equipe — nunca os de outro cliente, e nunca o conhecimento interno da Pluggy.

As ferramentas de documentação são públicas e somente leitura, exceto `submit_feedback`, que salva seu feedback para revisão humana. Não inclua credenciais ou dados pessoais no feedback. As ferramentas do portal de desenvolvedor requerem login. Para chamar a API do produto Pluggy diretamente, use a [Referência da API](/reference) com suas próprias credenciais.

## Seus próprios dados: as ferramentas do portal de desenvolvedor

Faça login e o agente pode responder perguntas sobre *sua* integração, não apenas sobre a documentação — por que um item está falhando, o que um webhook entregou, quanto você ingeriu no mês passado.

| Ferramenta | O que faz |
| --- | --- |
| `list_teams` | As equipes às quais sua conta pertence |
| `list_applications` | As aplicações de uma equipe, com seu ambiente |
| `select_application` | Define a equipe e a aplicação para o resto da conversa |
| `get_application` | Como uma aplicação está configurada — nome, ambiente (sandbox ou produção), habilitada, clientId, origens permitidas e branding. Nunca inclui o client secret |
| `list_connectors` | Os conectores disponíveis para uma aplicação |
| `get_stats` | Estatísticas do dashboard para uma equipe — itens, execuções, taxa de sucesso e volume e resultados de pagamentos |
| `get_item` | Um item por id: status atual e execuções recentes |
| `debug_item` | Por que um item está falhando, e o próximo passo para aquele usuário — credenciais expiradas, consentimento para re-autorização, MFA pendente, ou um incidente do lado do provedor |
| `get_execution_reports` | O que cada sincronização recente de um item trouxe — produtos com dados, vazios ou falhados, entidades retornadas, transações criadas por data. Para "a sincronização funcionou, mas os dados estão faltando" |
| `summarize_api_calls` | Como uma aplicação usou a API Pluggy ao longo de um período de até 7 dias — chamadas agrupadas por endpoint e status, com contagens e duração p95 |
| `list_api_calls` | Chamadas individuais da API de uma aplicação, da mais nova para a mais antiga — endpoint, status, código de erro, duração, o item que nomeou e o id da solicitação. Filtrar por classe de status, endpoint ou item |
| `summarize_of_calls` | Como as chamadas de Open Finance que a Pluggy fez para a instituição para um item ocorreram ao longo de um período de até 31 dias — por execução, endpoint e status, com contagens, tentativas e duração p95. Para "por que meu item falhou" ou "por que não trouxe transações" |
| `list_of_calls` | Chamadas individuais de Open Finance de um item, da mais nova para a mais antiga — execução, endpoint, status, código de erro, duração e tentativas. Filtrar por execução, classe de status ou endpoint |
| `check_incidents` | Incidentes atuais e recentemente resolvidos de [status.pluggy.ai](https://status.pluggy.ai), opcionalmente filtrados por conector |
| `list_webhooks` | Os webhooks registrados para uma aplicação e os eventos que eles disparam |
| `list_webhook_events` | Eventos entregues, com seu status |
| `get_webhook_event` | Um evento completo: payload, status, tentativas de entrega |
| `get_reports` | Relatórios de ingestão de transações ao longo de um intervalo de datas, diários ou resumidos |
| `get_billing_url` | Um link para o dashboard de faturamento da equipe |
| `create_support_ticket` | Abre um ticket de suporte — apenas para equipes com a integração de ticket de parceiro habilitada |
| `dev_portal_tools_introduction` | Como o agente deve encadear as ferramentas acima |

A primeira chamada pede que você faça login com a mesma conta que usa no
[Dashboard](https://dashboard.pluggy.ai), através do fluxo de autorização normal do seu cliente MCP. Não há chave de API para colar, e seu `clientSecret` nunca chega ao agente: as ferramentas leem o portal de desenvolvedor em nome do seu usuário, limitado às equipes que esse usuário já pode ver.

Uma sessão geralmente vai: `list_teams` → `list_applications` → `select_application`, e a partir daí as ferramentas de dados reutilizam essa equipe e aplicação. Pedir ao agente para "usar minha aplicação sandbox" é suficiente — ele faz essas chamadas por conta própria.

<Callout variant="warning" title="Faça login antes de perguntar, não depois">
A autenticação é opcional neste servidor: as ferramentas de documentação funcionam anonimamente, então um cliente configurado para autenticar **apenas quando o servidor pedir** nunca é solicitado, e as ferramentas do portal de desenvolvedor respondem *"Não autenticado"* em vez de abrir o login. Defina o conector para autenticar **sempre** (no Claude, *Sempre necessário*) e o fluxo funcionará como esperado.
</Callout>

### O que perguntar

```
Por que o item 8a7c… está preso? Use as ferramentas do portal de desenvolvedor da Pluggy.
```

```
Liste os eventos de webhook que minha aplicação de produção entregou hoje e abra o último que falhou.
```

```
Quantas transações nós ingerimos no mês passado em comparação com o anterior?
```

## Quando algo não funciona

- **O agente nunca chama as ferramentas.** Reinicie o cliente após adicionar o servidor — a maioria só lê sua configuração MCP na inicialização — e verifique se a URL é exatamente `https://mcp.pluggy.ai/mcp`.
- **"Não autenticado" em uma ferramenta do portal de desenvolvedor.** O cliente está configurado para fazer login apenas sob demanda; veja a nota acima.
- **A resposta parece desatualizada.** As ferramentas leem o site publicado, então qualquer coisa que ainda não foi publicada também não é visível para elas. Verifique a página em si em [v2.docs.pluggy.ai](https://v2.docs.pluggy.ai).
- **Seu cliente só fala stdio.** Faça a ponte com `npx -y mcp-remote https://mcp.pluggy.ai/mcp`.