# MCP Server

The Pluggy Docs **Model Context Protocol (MCP) server** lets any AI agent read Pluggy's documentation, guides, API reference, changelog, recipes, and curated support Q&A directly at runtime. Instead of guessing from stale training data, your agent answers questions and writes integration code grounded in the **live** docs — with citations.

The server is hosted at:

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

It's a remote HTTP server: **no installation, no API key.** Point any MCP-compatible client at that URL and it works.

The server now lives on its own address, so it stays the same even if the documentation site later moves — `https://mcp.pluggy.ai/mcp` is the URL to use from here on. The previous one, `https://v2.docs.pluggy.ai/api/mcp`, keeps working, so anything you already set up is fine as it is.

**One URL, optional sign-in — the same server for everyone:**

- **Without signing in** → the public documentation tools (docs, API reference, changelog, recipes, Q&A).
- **Signed in with your Pluggy dashboard account** → the above **plus your dev-portal tools** — your teams, applications, connectors, items, and usage — scoped to your team. Sign-in is optional; use it anonymously for docs, or connect it to your data.

> **Skills vs. MCP**
>
> The MCP server gives an agent live access to Pluggy's documentation at runtime. [Agent Skills](/docs/developer-tools/ai-skills) give the agent the know-how — the patterns and best practices — for building with Pluggy. They work independently, and even better together.

## What you can do with it

Once connected, ask your agent to build with Pluggy and it will pull the exact, current answer instead of hallucinating:

- **"How do I create a connect token and open the Connect Widget?"** → grounded steps from the live guides.
- **"Show me the details of the `createItem` endpoint."** → method, path, parameters, and schemas straight from the OpenAPI spec.
- **"What changed in the last release for webhooks?"** → the actual changelog entry, not a guess.
- **"Why is my item stuck in `WAITING_USER_INPUT`?"** → the curated, human-verified support Q&A that answered it before.
- **"Write the code to list a user's transactions with pagination."** → integration code that matches the current API.

Because it reads the same content published on this site, the answers stay correct as the docs evolve — you never re-teach your agent.

## Available tools

| Tool               | What it does                                                                                              |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `query`            | Ask a natural-language question and get a generated answer **with citations**, combining docs, changelog, recipes, and API reference |
| `search_docs`      | Search the documentation guides (concepts, quickstart, integration) with relevance-ranked excerpts        |
| `search_qa`        | Search the curated, human-verified support Q&A — the highest-trust source for "how do I / why does X happen" questions |
| `search_changelog` | Search the changelog — release notes, breaking changes, migration notes                                   |
| `search_recipes`   | Search the recipes — cookbook, integration patterns, code examples                                        |
| `get_guide`        | Retrieve the full content of a single documentation guide by slug and locale                              |
| `list_guides`      | List all documentation guides (slug, title, description, category) for a locale                           |
| `get_api_endpoint` | Get full details of an API endpoint by `operationId` — method, path, parameters, request body, responses  |
| `list_endpoints`   | List all Pluggy API endpoints from the OpenAPI spec, optionally filtered by tag                           |

## Connect it to your tool

Pick your agent below. Everywhere you see it, the server URL is the same: `https://mcp.pluggy.ai/mcp`.

### Claude Code

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

Add `-s user` to make it available in every project: `claude mcp add -s user --transport http pluggy-docs https://mcp.pluggy.ai/mcp`.

### Claude Desktop

**Settings → Connectors → Add custom connector**, name it `Pluggy Docs`, and paste `https://mcp.pluggy.ai/mcp`. Or edit `claude_desktop_config.json`:

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

### ChatGPT (OpenAI)

In **Settings → Connectors → Advanced → Developer mode**, add a connector with the URL `https://mcp.pluggy.ai/mcp`. (Custom remote MCP connectors are available on ChatGPT Plus/Pro/Business/Enterprise.) In a chat, enable the `Pluggy Docs` connector and ask away.

### OpenAI Codex CLI

Add to `~/.codex/config.toml`:

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

Codex talks to local (stdio) MCP servers, so `mcp-remote` bridges to the hosted HTTP server.

### Cursor

Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):

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

### VS Code (GitHub Copilot agent mode)

One command:

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

Or create `.vscode/mcp.json` in your workspace:

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

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

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

### Gemini CLI

Add to `~/.gemini/settings.json`:

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

### Zed

Add to your Zed `settings.json`:

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

### Any other MCP client

If your client only supports local (stdio) servers, bridge to the hosted one with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

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

Clients that support remote **Streamable HTTP** servers can use the URL directly.

## Test your setup

Start a new chat with your agent and try:

```
Using the Pluggy docs MCP, how do I create a connect token and open the Connect Widget?
```

or

```
List the Pluggy API endpoints for Items and show me the details of createItem.
```

The agent should call the MCP tools and answer with citations from the live documentation. If nothing happens, restart the client after adding the server and confirm the URL is exactly `https://mcp.pluggy.ai/mcp`.

## What it exposes

The server covers everything published on this site:

- **Documentation guides** — concepts, quickstart, and integration guides (EN, PT, ES)
- **API Reference** — every endpoint from the OpenAPI spec, with parameters and schemas
- **Changelog** — release notes, breaking changes, and migration notes
- **Recipes** — step-by-step integration patterns and code examples
- **Curated Q&A** — real support questions answered and verified by the Pluggy team

**Signed in** (your Pluggy dashboard account), the same server also exposes your **dev portal**, scoped to your team: list your teams and applications, connectors, items, and usage stats. Your token is validated and used only to reach your own team's data — never another customer's, and never Pluggy-internal knowledge.

The documentation tools are read-only and public; the dev-portal tools require sign-in. To call the Pluggy product API directly, use the [API Reference](/reference) with your own credentials.

## Your own data: the dev-portal tools

Sign in and the agent can answer questions about *your* integration, not only about the
documentation — why an item is failing, what a webhook delivered, how much you ingested
last month.

| Tool | What it does |
| --- | --- |
| `list_teams` | The teams your account belongs to |
| `list_applications` | The applications of a team, with their environment |
| `select_application` | Fixes the team and application for the rest of the conversation |
| `list_connectors` | The connectors available to an application |
| `get_stats` | Dashboard stats for a team — items, executions, success rate |
| `get_item` | One item by id: current status and recent executions |
| `debug_item` | Why an item is failing, and the next step for that user — expired credentials, consent to re-authorize, MFA pending, or a provider-side incident |
| `check_incidents` | Current and recently resolved incidents from [status.pluggy.ai](https://status.pluggy.ai), optionally filtered by connector |
| `list_webhooks` | The webhooks registered for an application and the events they fire on |
| `list_webhook_events` | Events delivered, with their status |
| `get_webhook_event` | One event in full: payload, status, delivery attempts |
| `get_reports` | Transaction-ingestion reports over a date range, daily or summarised |
| `get_billing_url` | A link to the team's billing dashboard |
| `create_support_ticket` | Opens a support ticket — only for teams with the partner ticket integration enabled |
| `dev_portal_tools_introduction` | How the agent should chain the tools above |

The first call asks you to sign in with the same account you use on the
[Dashboard](https://dashboard.pluggy.ai), through your MCP client's normal
authorization flow. There is no API key to paste, and your `clientSecret` never
reaches the agent: the tools read the dev portal on behalf of your user, scoped to the
teams that user can already see.

A session usually goes: `list_teams` → `list_applications` → `select_application`, and
from there the data tools reuse that team and application. Asking the agent to "use my
sandbox application" is enough — it makes those calls itself.

<Callout variant="warning" title="Sign in before you ask, not after">
Authentication is optional on this server: the documentation tools work anonymously,
so a client configured to authenticate **only when the server asks for it** never gets
asked, and the dev-portal tools answer *"Not authenticated"* instead of opening the
sign-in. Set the connector to authenticate **always** (in Claude, *Always required*)
and the flow works as expected.
</Callout>

### What to ask it

```
Why is item 8a7c… stuck? Use the Pluggy dev portal tools.
```

```
List the webhook events my production application delivered today, and open the last
failed one.
```

```
How many transactions did we ingest last month compared with the one before?
```

## When something does not work

- **The agent never calls the tools.** Restart the client after adding the server —
  most only read their MCP configuration at startup — and check the URL is exactly
  `https://mcp.pluggy.ai/mcp`.
- **"Not authenticated" on a dev-portal tool.** The client is set to sign in only on
  demand; see the note above.
- **The answer looks out of date.** The tools read the published site, so anything not
  yet published is not visible to them either. Check the page itself on
  [v2.docs.pluggy.ai](https://v2.docs.pluggy.ai).
- **Your client only speaks stdio.** Bridge with `npx -y mcp-remote https://mcp.pluggy.ai/mcp`.