MCP Server Setup

Quick start

The MCP server runs on each regional Sonar API host. Select every region your agent should reach — the generated .cursor/mcp.json includes one endpoint per region. You need an API key per organization region from Organization > API Keys.

Client configuration

Single-region setup. Enable all listed servers under Cursor Settings → MCP.

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

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

Permissions & scopes

API keys carry scopes that control which MCP tools the agent can call. Each tool requires a minimum scope — calls without it return a scope '...' required error naming the missing scope. A key can hold a global wildcard, one or more domain scopes, or both — pick domain scopes in the dashboard's API Keys panel to issue a key narrower than full read/write access.

Global wildcards

Domain scopes

Narrower alternative to the wildcards above — grant just what an integration needs, e.g. a key that can only execute_policy without touching catalogs or tables.

Read and write are independent per domain: a policies:write-only key can call create_policy and also list_policies (write implies read within the same domain), but nothing in the catalogs, tables, or query domains, and none of the cross-domain tools that require the bare read wildcard. The same independence applies to the global wildcards themselves — a write-only key does not gain read access unless read is also granted.

Response formats

Available tools

The MCP server exposes 27 tools across discovery, analysis, and governance. Agents auto-discover them via the standard MCP tool listing.

Read tools carry readOnlyHint. Only execute_policy carries destructiveHint — other write tools create or update policy definitions but do not run maintenance directly.

Built-in prompts

The same analysis workflows are registered as both MCP prompts and analyze_* tools. Claude Desktop can invoke prompts directly; Cursor and most agents should call the matching analyze_* tool and follow the returned instructions field.

Maintenance decisions

Sonar adaptive maintenance continuously samples each table and stores a maintenance sample with the logic for why compaction, snapshot expiry, or manifest rewrite should run. Fetch them via get_maintenance_signals: needs_compaction, needs_expire_snapshots, needs_rewrite_manifests, per-action scores, accumulation rates, and projected trigger times.

For table-level optimization, prefer get_table_profile or call analyze_table_maintenance for a full decision workflow. In Cursor, use analyze_policy_gaps, analyze_table_health, etc. — call the tool and follow the returned instructions field.

Policy safety: REMOVE_ORPHAN_FILES policies require an enabled EXPIRE_SNAPSHOTS or ADAPTIVE_MAINTENANCE policy in the same or broader scope — snapshot expiry must run before orphan cleanup.

Autocompletion & discovery

Sonar supports two complementary ways to resolve catalog, namespace, and table names:

• •Prompt autocomplete — when a client fills MCP prompt arguments (e.g. analyze_table_health), the server responds to completion/complete with live suggestions. Namespace and table completions use already-selected values from context.arguments (catalog → namespace → table).
• •Agent discovery tools — Cursor Agent does not autocomplete tool arguments. Agents should call list_catalogs, list_namespaces, or search_tables before table-scoped reads and analyze_* workflows.

Completions are registered for all built-in prompts. Up to 20 tenant-scoped suggestions per request.

Authentication & tenant isolation

Every MCP request passes through the same authentication layer as the REST API. Use an organization API key in the Authorization: Bearer header. The key is bound to your organization and data region — agents can only see and act on your tenant's data.

• •Unauthenticated requests — rejected with 401
• •Invalid or expired keys — rejected with 401
• •Insufficient scope — tool returns an error result (does not execute)
• •Cross-tenant access — not possible; tenant context is derived from the key, not from agent input

Troubleshooting