---
name: iblai-connect-plaid
description: "Read and write Plaid data through the Plaid API (Auth, Transactions, Balance, Identity, Transfer) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Plaid data, or to set up a Plaid MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Plaid connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/plaid — not part of the iblai/vibe repository. Checked against Plaid's documentation on October 20, 2026; test it against your own Plaid setup before you rely on it.

Plaid connects apps to people's bank, card and investment accounts. Through it an app reads account and routing numbers, balances, transactions and identity data, and can move money with Transfer.

## Auth & conventions

- **API:** Plaid API (Auth, Transactions, Balance, Identity, Transfer) (REST). JSON over HTTPS POST. A user links accounts in Link; the app exchanges the public_token for an access_token per Item, then calls product endpoints. Errors come back as error_code and error_type.
- **Base URL:** https://sandbox.plaid.com (Sandbox) / https://production.plaid.com (Production)
- **Access:** Public, self-serve. Sign up in the Plaid Dashboard for a client_id and a secret per environment. Sandbox uses test credentials and simulated data; Production access is approved per product.
- **Auth:** API key (client_id and secret); Link token flow (public_token exchanged for access_token). Send client_id and secret in the JSON body or as PLAID-CLIENT-ID and PLAID-SECRET headers. /link/token/create starts Link; /item/public_token/exchange returns an access_token to keep server-side.
- **Limits:** Production defaults, fixed windows: /accounts/balance/get 5/min and 30/hour per Item; /transactions/sync 50/min per Item; /auth/get and /identity/get 15/min per Item; client-wide caps also apply.
- Keep Plaid credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Account and routing numbers** — /auth/get returns account and routing numbers for checking and savings accounts on an Item.
- **Transactions** — /transactions/sync returns added, modified and removed transactions since the last cursor.
- **Real-time balance** — /accounts/balance/get fetches current balances from the institution.
- **Identity** — /identity/get returns account-holder names, addresses, emails and phone numbers.
- **Item status** — /item/get returns institution, products, consent and error status for an Item.

## Writes

- **Link token** — /link/token/create starts a Link session for a user.
- **Transfers** — /transfer/authorization/create then /transfer/create moves money from a linked account. **Confirm with the user first.**
- **Cancel transfer** — /transfer/cancel cancels a pending transfer. **Confirm with the user first.**
- **Remove Item** — /item/remove invalidates the access_token and related processor tokens; cannot be undone. **Confirm with the user first.**

## Expose it to an ibl.ai agent (MCP)

Plaid publishes an official MCP server, Plaid Dashboard MCP server (https://plaid.com/docs/resources/mcp/). Register it below as-is, or host your own server that wraps the calls in this skill.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - For an API key or service credential use `auth_type=token` with `auth_scope=platform` for one key across the organization, or scope it to a single agent for one key per agent.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "Sync new transactions for this user's linked checking account since the last cursor"
- "What is the available balance on the account we will debit for this payment?"
- "Why did Link conversion drop for Chase users last week?"
- "Debug why this Item is returning ITEM_LOGIN_REQUIRED"

## Guardrails

- Account and routing numbers, balances, transactions and identity data are GLBA nonpublic personal information. access_tokens are long-lived secrets and must stay on the server.
- Request the narrowest Plaid scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- Plaid API reference: https://plaid.com/docs/api/
- Plaid Quickstart: https://plaid.com/docs/quickstart/
- Plaid Dashboard MCP server: https://plaid.com/docs/resources/mcp/
- Plaid Dashboard MCP server: https://plaid.com/docs/resources/mcp/
- This connector on ibl.ai: https://ibl.ai/developer/connectors/plaid
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections