Connect your agent

Midplane exposes a single MCP endpoint. Point your agent’s MCP config at it, and from then on the agent reaches your database only through Midplane — every query is parsed, checked against your policy, and written to the audit trail before it runs. There’s no per-agent integration to build and no allow-list to get onto. Any client that speaks MCP connects the same way — Cursor, Claude Code, Claude Desktop, ChatGPT, VS Code, Windsurf, Zed, and others. The client registers itself, you sign in once, and you choose exactly which databases that agent can reach. The only thing that differs between clients is where you paste the URL — see connect your client.

Connect your client

Every client reaches the same endpoint and signs in once over OAuth — only how you point it there differs. Pick your client below; each uses the Cloud endpoint URL, so swap in http://localhost:3000/mcp for self-host. If the tools don’t appear, see troubleshooting.

Cursor
Claude Code
VS Code
Claude Desktop
Any other client

One-click — install from a link (pick your region): Add to Cursor · EU · Add to Cursor · USOr add it by hand — Cursor reads MCP servers from ~/.cursor/mcp.json and auto-detects Streamable HTTP from the URL, so no transport or type key is needed:

~/.cursor/mcp.json

{
  "mcpServers": {
    "midplane": {
      "url": "https://{eu|us}.midplane.ai/mcp"
    }
  }
}

Either way, Cursor walks you through the OAuth sign-in, then its MCP panel lists the Midplane tools.

claude mcp add --transport http midplane https://{eu|us}.midplane.ai/mcp

--transport http is required. Without it, the CLI defaults to stdio and treats the URL as a launcher command to execute — which fails silently. If Midplane never connects, this flag is almost always why.

The first call triggers the OAuth sign-in. Confirm it registered with claude mcp list.

One-click — install from a link (pick your region): Install in VS Code · EU · Install in VS Code · USOr add it by hand — run MCP: Add Server from the Command Palette and give it the endpoint URL over HTTP, or drop it into .vscode/mcp.json:

.vscode/mcp.json

{
  "servers": {
    "midplane": {
      "type": "http",
      "url": "https://{eu|us}.midplane.ai/mcp"
    }
  }
}

VS Code then walks you through the OAuth sign-in and lists the Midplane tools.

Claude Desktop attaches a remote MCP server two ways, depending on your deployment:

Cloud — the HTTPS endpoint drops straight into Settings → Connectors → Add custom connector. Name it midplane, paste the endpoint, save, then sign in once when prompted.
Self-host — the Custom Connectors UI rejects http://localhost, so use the mcp-remote stdio shim. Open your claude_desktop_config.json from Settings → Developer → Edit Config (the path varies by OS) and add:

claude_desktop_config.json

{
  "mcpServers": {
    "midplane": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

mcp-remote is fetched on demand by npx, so you need Node.js on your PATH.

Restart Claude Desktop after editing the file. New MCP servers don’t hot-reload.

Any client that supports remote MCP servers over OAuth connects the same way — ChatGPT, Windsurf, Zed, and others. There’s nothing Midplane-specific to install:

Open your client’s add MCP server (or add connector) setting.
Give it the endpoint URL — https://{eu|us}.midplane.ai/mcp (Cloud) or http://localhost:3000/mcp (self-host). If the client asks for a transport, choose Streamable HTTP.
The client registers itself and walks you through the OAuth sign-in. Approve the scope, and the Midplane tools appear.

If your client can’t reach a remote MCP server directly, bridge it with the mcp-remote stdio shim shown in the Claude Desktop tab.

Or let your agent connect itself

If your client is an agentic CLI or IDE that can run its own commands — Claude Code, Cursor, Windsurf, Codex, and the like — let it wire itself up instead. Pick your deployment and paste the prompt into that client; it adds Midplane, then hands back to you for the one-time browser sign-in. A UI-only client like Claude Desktop or ChatGPT has no shell for the agent to drive, so use the by-hand tabs above.

Cloud · EU
Cloud · US
Self-host

Setup prompt

Add Midplane as an MCP server in this client, over Streamable HTTP (MCP `type: "http"`).
My endpoint is https://eu.midplane.ai/mcp.

Add it using whatever this client uses to register a remote MCP server — its own
CLI, config file, or add-server command. Setup details vary by client and version,
so use the client's current method rather than a fixed command. One known gotcha:
in Claude Code, `claude mcp add` needs the `--transport http` flag, or it treats
the URL as a stdio command and fails silently.

Don't invent or ask me for an auth token — Midplane authorizes over OAuth. After
you add the server, trigger a connection and hand back to me to sign in in the
browser. Once it's connected, confirm the Midplane tools (`query`, `list_tables`,
`describe_table`) appear.

Setup prompt

Add Midplane as an MCP server in this client, over Streamable HTTP (MCP `type: "http"`).
My endpoint is https://us.midplane.ai/mcp.

Add it using whatever this client uses to register a remote MCP server — its own
CLI, config file, or add-server command. Setup details vary by client and version,
so use the client's current method rather than a fixed command. One known gotcha:
in Claude Code, `claude mcp add` needs the `--transport http` flag, or it treats
the URL as a stdio command and fails silently.

Don't invent or ask me for an auth token — Midplane authorizes over OAuth. After
you add the server, trigger a connection and hand back to me to sign in in the
browser. Once it's connected, confirm the Midplane tools (`query`, `list_tables`,
`describe_table`) appear.

Setup prompt

Add Midplane as an MCP server in this client, over Streamable HTTP (MCP `type: "http"`).
My endpoint is http://localhost:3000/mcp.

Add it using whatever this client uses to register a remote MCP server — its own
CLI, config file, or add-server command. Setup details vary by client and version,
so use the client's current method rather than a fixed command. One known gotcha:
in Claude Code, `claude mcp add` needs the `--transport http` flag, or it treats
the URL as a stdio command and fails silently.

Don't invent or ask me for an auth token — Midplane authorizes over OAuth. After
you add the server, trigger a connection and hand back to me to sign in in the
browser. Once it's connected, confirm the Midplane tools (`query`, `list_tables`,
`describe_table`) appear.

Prefer to understand what’s happening under the hood? Read on for the endpoint, what you grant at consent, and the rest of the flow.

How connecting works

It’s the same three steps for every client:

Point your client at the endpoint

Add Midplane as an MCP server, using the endpoint URL below. No token to paste.

The first time your client connects, it registers itself and hands you off to Midplane to sign in over OAuth. This is standard MCP authorization — the client does it automatically; you never copy a client ID or secret.

Grant least-privilege scope

At sign-in you approve the agent and choose its scope: which project it connects to, which of that project’s databases it can reach, and whether each is read or read_write. See what you grant at consent.

Once connected, the agent’s tools appear in your client, and every call it makes runs through the engine.

The endpoint

The endpoint URL depends on how you run Midplane:

Cloud URL
Self-host URL

https://{eu|us}.midplane.ai/mcp

Your account’s MCP endpoint, with the region in the host. There’s no token or project id in the path — the URL is an address, not a secret, so it’s safe to copy and share. Your client registers itself and you sign in once over OAuth; the project it reaches is the one you pick at consent. Copy the URL from the dashboard. See projects.To bind a client straight to one project (handy when a client reaches several), use the explicit form https://{eu|us}.midplane.ai/mcp/<projectId>.

http://localhost:3000/mcp

The local control-plane URL your deployment exposes. See deploy to boot it.

Transport

Midplane speaks MCP over Streamable HTTP, the current MCP transport — one endpoint that handles every call. Most clients (Cursor, Claude Code, ChatGPT, VS Code) connect to that URL directly. A few — notably Claude Desktop against a http://localhost self-host endpoint — need a small stdio shim (mcp-remote) that bridges stdio to the same HTTP endpoint. Sign-in is also where you set the agent’s scope — least privilege, chosen the moment it connects. The consent screen names the agent asking to connect (by the name it registered under) and asks you to grant:

One project. Each agent credential is bound to a single project. If your account has one project it’s selected for you; with several, you pick — Midplane never silently defaults the choice, so an agent can’t bind to the wrong project.
Which databases. Check only the databases on that project the agent should reach. Nothing is checked by default — granting is opt-in, per database.
read or read_write for each. The least-privilege default is read.

The grant is enforced on every request: the agent reaches only the databases you checked, at the access you set. In Cloud, an agent with no grant is denied — the scope fails closed. (Self-host is single-tenant, so an empty grant instead leaves the owner’s agent unscoped — full reach across the project, still bounded by policy — rather than locking the owner out of its own data.) Midplane also shows the identity details the client reads (your name, your email), so there are no hidden scopes.

Per-agent scope sits on top of the project policy — it doesn’t replace it. The policy is the ceiling for every agent on the project; the consent grant narrows one credential below that ceiling. See per-agent database scope.

To change an agent’s scope later, reconnect it — the consent screen pre-selects its current grant — or revoke it.

Machine and CI agents

OAuth covers interactive agents. For headless callers — CI jobs, scheduled tasks, anything without a browser — mint a machine token instead and present it as a bearer header:

Authorization: Bearer mp_live_…

A machine token carries the same kind of scope as the consent screen — read or read_write per database — except you set it when you mint the token. The token is a secret, shown once at creation; store it like any other credential. Clients that can’t set a header can use the legacy https://{eu|us}.midplane.ai/mcp/<token> URL form.

Manage connected agents

In Cloud, every agent connected to a project — interactive OAuth clients and headless tokens alike — appears in the project’s Agents pane. Revoke any agent and its access stops on the next request — there’s no waiting for a credential to expire. Revoke the moment a laptop or runner goes missing. See projects & access for the Agents pane and the machine-token lifecycle.

The tools your agent gets

Once connected, the agent sees a small, fixed set of tools:

Tool	What it does
`query`	Run a single SQL statement through the policy engine.
`list_tables`	List the tables the agent can see.
`describe_table`	Return a table’s columns and types.
`list_databases`	List each database and its policy summary. Registered only when you configure multiple databases (`0.2.0+`).

Every query call also carries an intent — a short, plain-language “why,” filled in by the agent automatically, that lands on the audit row next to the SQL and the decision. It’s recorded for the audit trail only; it never relaxes or tightens a decision, which is made on the parsed SQL. For the full argument and response shapes, see the MCP tools reference.

Try it

With the tools connected, run these prompts to confirm the engine is enforcing policy. The first is an allowed read; the rest each hit a different rule.

List the tables — allowed

“What tables are in the database?”The agent calls list_tables and returns your tables. This is a read, so the default read-only policy allows it.

Delete all users — denied by table access

“Delete all users.”The agent calls query with DELETE FROM users. Midplane denies it: writes are read-only by default, so the table_access rule blocks the statement, naming the table and the policy key you’d flip to grant the write. See table access.

Stacked statements — denied by multi-statement

“Run this SQL: SELECT 1; DROP TABLE users”Two statements in one call. The multi_statement rule denies it at parse time — the stacked DROP never reaches the database.

Each call lands in the audit trail. An allowed query records ATTEMPTED → DECIDED → EXECUTED; a denied query stops at ATTEMPTED → DECIDED and never executes.

Get started

Core concepts