Connect Your Agent

AI agents reach LakeOps through the Model Context Protocol (MCP). Each region's API host serves an MCP server at /mcp. Your MCP client sends an organization API key as Authorization: Bearer, and the agent gets tools to inspect tables, plan and run maintenance, and manage policies.

How the connection works

  • •Nothing to install from LakeOps. There is no LakeOps CLI, SDK, or local server. Your MCP client talks to the hosted endpoint over HTTPS.
  • •Same auth as the REST API. The key decides the organization, so an agent can only see that organization's catalogs. Each tool then checks the key's scopes before it runs.
  • •Tools, not SQL. MCP exposes LakeOps metadata and operations. It does not run ad-hoc SQL against your tables — that is POST /api/query/{catalogName} on the REST API.

Before you start, connect at least one catalog (Quick Start) so the agent has something to see.

1. Create a scoped API key

In the LakeOps console, open Organization > API Keys and click Create API Key. Only organization admins can create API keys; ask an admin if Organization > API Keys isn't available to you. Name the key after the agent (for example cursor-agent), pick its permissions, and optionally set an expiration (30 days to 1 year). Copy the key when it is shown — it is displayed once.

Use this key for every agent. Console sign-in tokens expire within minutes and do not carry key scopes, so they are not a way to connect an agent.

Choose the key's scopes

Give the agent the least it needs. Start read-only, then create a second key when you want the agent to change things.

Key profileScopes
Read-only (start here)readGrant full read
Run maintenancereadtables:writeGrant full read, then Tables: Write
Manage policiesreadpolicies:writeGrant full read, then Policies: Write
  • •Keep the bare read scope on every agent key. Domain scopes such as tables:read cover single-table tools, but the analyze_* workflows, get_table_events, and get_lake_health require read itself.
  • •Leave off tables:delete and the global write scope unless the agent should be able to call delete_table. Global write includes table deletion. Over MCP, tables:write does not, but the REST delete route accepts tables:write, so do not reuse a maintenance key in scripts that should never delete tables.

In the key form, Grant full read and Grant full write add the global scopes, and each checkbox adds one domain scope. Unchecking a box that a Grant full button filled in keeps the other domains as individual scopes.

In the consoleScope ID
Grant full readread
Grant full writewrite
Policies: Read / Writepolicies:readpolicies:write
Catalogs: Read / Writecatalogs:readcatalogs:write
Tables: Read / Write / Deletetables:readtables:writetables:delete
Query: Readquery:read

Tables: Delete lets the MCP delete_table tool permanently delete tables. Deleting a table cannot be undone.

The scope each tool requires is listed in the MCP Server tool reference.

2. Pick your regions

LakeOps runs globally, with data regions across most major cloud regions. Each region has its own MCP server at /mcp on its API host. Pick the region you sign in to; the popular regions below are examples, and your selection fills in every config snippet on this page.

Don't see your region? Contact support for its API host.

GlobalPopular regions

Each region is its own MCP server entry named lakeops-{region}. A region only holds the catalogs connected in that region, so configure the regions where your catalogs live. With more than one entry, name the server in your prompt (for example lakeops-eu-west-1) so the agent calls the right one.

3. Configure your client

Single-region setup. Replace each <your-api-key-…> placeholder with the key from step 1.

Claude Code

Paste in a terminal. Claude Code connects over Streamable HTTP and sends the header on every request.

claude mcp add --transport http lakeops-us-east-1 https://api.lakeops.dev/mcp --header "Authorization: Bearer <your-api-key-us-east-1>"

Cursor

Paste in a terminal. Cursor opens and asks you to confirm the install. On Linux, replace open with xdg-open.

open "cursor://anysphere.cursor-deeplink/mcp/install?name=lakeops-us-east-1&config=$(printf '%s' '{"url":"https://api.lakeops.dev/mcp","headers":{"Authorization":"Bearer <your-api-key-us-east-1>"}}' | base64 | tr -d '\n' | sed 's/+/%2B/g;s/\//%2F/g;s/=/%3D/g')"
Prefer editing mcp.json?

Add to .cursor/mcp.json in the project root (or ~/.cursor/mcp.json for every project), then enable each server under Cursor Settings → MCP.

{
  "mcpServers": {
    "lakeops-us-east-1": {
      "url": "https://api.lakeops.dev/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key-us-east-1>"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json only starts local (stdio) servers, so it reaches LakeOps through mcp-remote, an open-source bridge that LakeOps does not maintain. It needs Node.js. Restart Claude Desktop after saving.

{
  "mcpServers": {
    "lakeops-us-east-1": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.lakeops.dev/mcp",
        "--header",
        "Authorization:${LAKEOPS_AUTH}"
      ],
      "env": {
        "LAKEOPS_AUTH": "Bearer <your-api-key-us-east-1>"
      }
    }
  }
}

Any other MCP client

Use the Streamable HTTP transport with URL https://api.lakeops.dev/mcp and header Authorization: Bearer <api-key>. The server is stateless: it answers POST requests with JSON and does not open an SSE stream, so clients that only speak the legacy SSE transport cannot connect.

4. Confirm the agent can see the lake

Ask the agent for a read-only call first. Name the server so a multi-region setup calls the right one.

Prompt

Using the lakeops-us-east-1 MCP server, call list_catalogs.
List each catalog's name, type, status, and tableCount. Do not change anything.

You should see the catalogs your organization connected in that region. An empty list usually means the server URL points at a different region. An error naming a scope means the key lacks it.

To check the key and URL without a client, call the tool directly. Export the key as LAKEOPS_API_KEY first.

curl -s https://api.lakeops.dev/mcp \
  -H "Authorization: Bearer $LAKEOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_catalogs","arguments":{}}}'

A working key returns a JSON-RPC result whose content[0].text is the catalog list as a JSON string.

Next

  • •Manage the Lakehouse — prompts for triage, maintenance decisions, running operations, and policies.
  • •MCP Server — every tool, its arguments, scopes, and response format.

Troubleshooting

SymptomFix
HTTP 401The key is missing, mistyped, revoked, or expired, or the header is not Authorization: Bearer <key>.
HTTP 403The key is not an organization key, has no scopes at all, or the organization has no LakeOps workspace on that host. Create the key from Organization > API Keys with at least one scope, and check the URL.
HTTP 400 or 405 from a raw HTTP callSend a POST with Accept: application/json, text/event-stream. GET is not supported.
Tool returns scope '…' requiredThe connection works; the key lacks that tool's scope. Create a key with the scope named in the error. A key with only write cannot call read tools — write does not include read.
Tools do not appear in the clientEnable each server in the client. The URL must end in /mcp and the client must use Streamable HTTP.
Empty catalog listThe server entry points at a region with no catalogs for your organization. For US East (N. Virginia), the host is api.lakeops.dev and the URL is https://api.lakeops.dev/mcp.
Agent calls the wrong regionName the server in the prompt (e.g. lakeops-us-east-1) or remove entries you do not need.