> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleander.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Coding with agents

> Give your coding agent access to your lake, pipelines, and lineage through the oleander MCP server and CLI.

oleander exposes a remote [MCP server](https://modelcontextprotocol.io) and a [CLI](/cli/introduction) 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](/mcp/claude#claude-cowork), see [Claude setup](/mcp/claude).

## 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](/platform/query-routing) parses the SQL, estimates how much data the referenced tables hold, and picks the engine and machine size to match - [Bloom](/platform/bloom) for most reads, DuckDB for mutations and [external connections](/platform/connections/bigquery), [Polars](/platform/polars) for DataFrame scripts, [Spark](/platform/spark/jobs) 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

<Tabs>
  <Tab title="MCP (Claude)">
    The [oleander Claude Code Plugin](https://github.com/OleanderHQ/claude-plugin) is a convenient way to install the oleander MCP server into Claude Code.

    ```bash theme={null}
    /plugin marketplace add OleanderHQ/claude-plugin
    /plugin install oleander@oleander
    ```

    Then authenticate:

    ```bash theme={null}
    claude mcp login oleander
    ```

    See [Claude setup](/mcp/claude) for [Claude Cowork](/mcp/claude#claude-cowork), skills, and manual MCP configuration.
  </Tab>

  <Tab title="MCP (Codex)">
    Add to `~/.codex/config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "oleander": {
          "type": "streamableHttp",
          "url": "https://oleander.dev/mcp"
        }
      }
    }
    ```

    See [Codex setup](/mcp/codex) for details.
  </Tab>

  <Tab title="MCP (Cursor)">
    Add to `.cursor/mcp.json`, then authenticate:

    ```bash theme={null}
    agent mcp login oleander
    ```

    See [Cursor setup](/mcp/cursor) for details.
  </Tab>

  <Tab title="MCP (OpenCode)">
    ```bash theme={null}
    opencode mcp add oleander --url https://oleander.dev/mcp
    opencode mcp auth oleander
    ```

    See [OpenCode setup](/mcp/opencode) for details.
  </Tab>

  <Tab title="CLI">
    <CodeGroup>
      ```bash Homebrew theme={null}
      brew tap OleanderHQ/tap
      brew install oleander-cli
      ```

      ```bash Ubuntu (APT) theme={null}
      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
      ```
    </CodeGroup>

    Authenticate with the API key from your [oleander settings](https://oleander.dev/app/settings/api-keys).

    ```bash theme={null}
    oleander configure --api-key <YOUR_API_KEY>
    ```

    See the [CLI reference](/cli/introduction) for all available commands.
  </Tab>
</Tabs>

## 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](https://registry.modelcontextprotocol.io) 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](https://smithery.ai/servers/peter-5dn5/oleander), and the aggregators sync from the official registry.

If your agent prefers to read setup instructions itself, point it at [`oleander.dev/llms.txt`](https://oleander.dev/llms.txt) or hand it [`oleander.dev/install.md`](https://oleander.dev/install.md) directly.

See the [MCP reference](/mcp/protocol) for every tool the server exposes.