Skip to content
PlaidCloud

Getting Started with AI Coding Agents

What is the MCP Server?

Section titled “What is the MCP Server?”

The Model Context Protocol is an open standard for letting AI agents talk to external tools and data. PlaidCloud runs an MCP server on every workspace that wraps the same core helpers the REST API uses — grouped by intent (find, describe, upsert, run, organize) so an agent can navigate the surface without loading 1,000+ low-level RPC method names.

The server lives at:

https://<your-workspace>.plaid.cloud/mcp

Replace <your-workspace> with your workspace subdomain (whatever you use to log into the PlaidCloud UI).

What It Exposes

Section titled “What It Exposes”

The catalog covers most of the day-to-day surface an agent needs:

  • Projects, workflows, steps — find/describe/upsert/run/organize, including step-level rerun and version history.
  • Tables, views, queries — schema introspection, query execution, exports, snapshots, branches.
  • Dimensions — describe, find, upsert, version, manage nodes/aliases/properties.
  • Connections — find/upsert/test connections to external systems.
  • Lakehouse — branches, snapshots, optimize/vacuum operations.
  • Identity — members, groups, sessions, distros.
  • Documents, dashboards, UDFs, editors, agents, publishes — domain-specific tools.
  • Alteryx migration — convert Alteryx workflows staged in Document and coordinate portfolio migration work.
  • Workflow logs and run tracking — workflow_logs, workflow_run_status, workflow_job_track.

Every tool returns a uniform envelope {ok, data, next_cursor?, total?}; failures use {ok: false, error: {code, retryable, message, hint?}}. Mutations accept dry_run=True for plan-without-write validation.

Keeping Results Small

Section titled “Keeping Results Small”

Tool results are the largest single consumer of an agent’s context, so the find and describe tools default to a modest slice and let you widen it:

  • Rows. A find returns 25 matches per page (step_find returns 50). A capped page sets next_cursor, and the find tools additionally name the clipped list in truncated — either one means “there is more”, not “that is all of them”. total always reports the full count. Raise limit or page with the cursor.
  • Columns. Pass fields=['id', 'name', 'update_time'] to get only those columns back. A field name that appears on no record is an error listing the available fields, not a silent omission — so a typo fails loudly instead of quietly returning less than you asked for. Tools that offer curated sets also take field_set='minimal' | 'default' | 'full'; call mcp_introspect to see which parameters a given tool accepts.
  • Counts. count_only=True sizes a result set without fetching it.

Column-Oriented Results

Section titled “Column-Oriented Results”

A large result whose rows all carry the same fields comes back column-oriented rather than as a list of objects, so the field names are sent once instead of once per row:

{"_fmt": "cols", "cols": ["id", "name"], "rows": [["a1", "Sales"], ["b2", "Costs"]]}

Row i is dict(zip(cols, rows[i])). Small results, and any result whose rows don’t share an identical set of fields, stay as ordinary arrays of objects — so both shapes appear, and code reading these responses directly should handle each. The envelope around it is unchanged, and no value is converted or rounded on the way. Agents are told about this shape when they connect and read it without any prompting from you; the saving is around 30% of the characters and around 15% of an agent’s reading budget on typical listing traffic, which is context left over for your actual question. (The two figures differ because repeated field names are cheap for a model to read — the character saving is always the larger of the two.)

For the live catalog, point your agent at the server and call mcp_introspect (no arguments) — that returns the current tool count, per-domain summaries, and parameter signatures. Use mcp_recipes for common multi-tool playbooks (paginating large lists, snapshot-then-modify, rerun a failed step, etc.).

Authentication

Section titled “Authentication”

PlaidCloud’s MCP server accepts two authentication paths:

  1. OAuth 2.1 + PKCE via Dynamic Client Registration (DCR). This is what Claude.ai’s custom-connector UI uses, and it’s also the default for Claude Code’s MCP bridge. The client registers itself, redirects you to PlaidCloud’s Keycloak login, and gets back a token transparently. You don’t need to do anything other than pick “OAuth” in the client and approve the login.
  2. Static Bearer token in an Authorization header. For agent runtimes that don’t have a usable browser redirect or that want a long-lived token in a config file. PlaidCloud exposes a helper page to mint one for you (see below).

Getting a Static Bearer Token

Section titled “Getting a Static Bearer Token”

Open this URL in a browser tab where you’re already signed into PlaidCloud:

https://<your-workspace>.plaid.cloud/mcp/setup/token

The page returns a JSON snippet ready to paste into your agent’s MCP config. Each workspace has its own snippet.

The token’s lifespan is governed by your Keycloak realm’s access-token-lifespan policy (typically a few hours to a day). To refresh, reload the same URL — your browser session re-mints the token automatically.

Pick a Client

Section titled “Pick a Client”

The rest of this section walks through setup for specific AI agent clients: