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 profile | Scopes | What the agent can do |
|---|---|---|
| Read-only (start here) | readGrant full read | Every discovery, get_*, and analyze_* tool, plus query_compaction and get_compaction_job_status. Nothing in the lake changes. |
| Run maintenance | readtables:writeGrant full read, then Tables: Write | Adds execute_optimization: run one maintenance operation on one table now. Over the REST API, the same key can also rename, roll back, and delete tables. |
| Manage policies | readpolicies:writeGrant full read, then Policies: Write | Adds create_policy, update_policy, enable_policy, disable_policy, and execute_policy. |
- •Keep the bare
readscope on every agent key. Domain scopes such astables:readcover single-table tools, but theanalyze_*workflows,get_table_events, andget_lake_healthrequirereaditself. - •Leave off
tables:deleteand the globalwritescope unless the agent should be able to calldelete_table. Globalwriteincludes table deletion. Over MCP,tables:writedoes not, but the REST delete route acceptstables: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 console | Scope ID |
|---|---|
| Grant full read | read |
| Grant full write | write |
| Policies: Read / Write | policies:readpolicies:write |
| Catalogs: Read / Write | catalogs:readcatalogs:write |
| Tables: Read / Write / Delete | tables:readtables:writetables:delete |
| Query: Read | query: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.
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
| Symptom | Fix |
|---|---|
| HTTP 401 | The key is missing, mistyped, revoked, or expired, or the header is not Authorization: Bearer <key>. |
| HTTP 403 | The 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 call | Send a POST with Accept: application/json, text/event-stream. GET is not supported. |
Tool returns scope '…' required | The 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 client | Enable each server in the client. The URL must end in /mcp and the client must use Streamable HTTP. |
| Empty catalog list | The 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 region | Name the server in the prompt (e.g. lakeops-us-east-1) or remove entries you do not need. |
