Coding with agents

oleander exposes a remote MCP server and a CLI that agents can use to query, run, and reason about your data infrastructure without leaving the editor. Wire either one up once and your agent gains the full context of your lake:

Tables and catalogs
Run history and lineage
Costs, logs, and traces

For plugins, skills, and setup in Claude Code and Claude Cowork, see Claude setup.

What agents can do

With the MCP server connected, an agent can:

Query your Iceberg lake tables directly with SQL
Upload and submit Spark jobs, then monitor their progress
Pull run lineage, cost breakdowns, and logs for any pipeline execution
Discover and inspect catalog tables and schemas
Investigate failures and surface downstream impact before shipping a change

A common pattern is building or debugging a data pipeline end to end from the editor: the agent reads from your lake, writes a transformation, submits it, then verifies the output and lineage without you switching contexts.

Cost-aware compute routing

The agent does not pick an engine. It calls query_run for reads and query_submit for writes, and oleander’s query routing layer parses the SQL, estimates how much data the referenced tables hold, and picks the engine and machine size to match - Bloom for most reads, DuckDB for mutations and external connections, Polars for DataFrame scripts, Spark for DDL and the largest jobs. The decision and the reasoning behind it come back in engine_decision, so the agent can explain why a query ran the way it did. explain: true returns that decision, the estimated input size, and the sandbox tier without running anything or spending compute - worth doing before a query you expect to be large. Because the agent also sees cost per run, it can prefer the cheaper path for a workload and scale up only when needed.

Install

MCP (Claude)
MCP (Codex)
MCP (Cursor)
MCP (OpenCode)
CLI

The oleander Claude Code Plugin is a convenient way to install the oleander MCP server into Claude Code.

/plugin marketplace add OleanderHQ/claude-plugin
/plugin install oleander@oleander

Then authenticate:

claude mcp login oleander

See Claude setup for Claude Cowork, skills, and manual MCP configuration.

Add to ~/.codex/config.json:

{
  "mcpServers": {
    "oleander": {
      "type": "streamableHttp",
      "url": "https://oleander.dev/mcp"
    }
  }
}

See Codex setup for details.

Add to .cursor/mcp.json, then authenticate:

agent mcp login oleander

See Cursor setup for details.

opencode mcp add oleander --url https://oleander.dev/mcp
opencode mcp auth oleander

See OpenCode setup for details.

brew tap OleanderHQ/tap
brew install oleander-cli

sudo apt-get update
sudo apt-get install -y curl ca-certificates gnupg

curl -fsSL https://oleander-cli-releases.s3.amazonaws.com/keys/oleander-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/oleander-archive-keyring.gpg >/dev/null

sudo tee /etc/apt/sources.list.d/oleander.sources >/dev/null <<'EOF'
Types: deb
URIs: https://oleander-cli-releases.s3.amazonaws.com/apt
Suites: stable
Components: main
Signed-By: /usr/share/keyrings/oleander-archive-keyring.gpg
EOF

sudo apt-get update
sudo apt-get install -y oleander-cli

Authenticate with the API key from your oleander settings.

oleander configure --api-key <YOUR_API_KEY>

See the CLI reference for all available commands.

How it works

Both the MCP server and CLI authenticate with your oleander API key. The MCP server runs remotely at https://oleander.dev/mcp and streams tool results back to your agent over the Model Context Protocol. The CLI is a local binary that talks to the same API. Use the MCP when working interactively with a coding agent. Use the CLI when scripting, automating, or running from a pipeline.

Finding the server

oleander is published to the official MCP registry as dev.oleander/oleander, under a DNS-verified oleander.dev namespace, so clients that install by name can find it without a hand-written config. It is also listed on Smithery, and the aggregators sync from the official registry. If your agent prefers to read setup instructions itself, point it at oleander.dev/llms.txt or hand it oleander.dev/install.md directly. See the MCP reference for every tool the server exposes.

Getting Started

Platform

Connections