MCP Tools Reference

The oleander MCP server exposes your context graph - lake tables, catalogs, pipeline runs, lineage, costs, logs, and traces - to any MCP-compatible agent.

Endpoint

https://oleander.dev/mcp

Authenticate with your oleander API key via Authorization: Bearer. Most MCP clients handle this automatically after the OAuth flow. The server is published to the official MCP registry as dev.oleander/oleander, so most clients can install it by name.

Example workflow

A typical agent task chains three tools:

catalogs_list       → discover available tables
query_run           → SELECT from a table
jobs_lineage_get    → trace what that run read and wrote

The agent calls these in sequence, each result informing the next, without you specifying the order.

Tools

Queries

Reads and writes go to different tools. query_run is annotated read-only so clients can skip the confirmation prompt; query_submit is annotated as a write and asks first.

Tool	Description
`query_run`	Run a query and get rows back on the call. The router picks the engine and machine size, so leave `engine` on `auto`; the choice comes back in `engine_decision`. Read-only - mutating SQL is rejected before it executes. Pass `explain: true` to see the plan without spending compute, or `script` to run a Polars DataFrame script.
`query_submit`	Everything that changes data: a `SELECT` plus a `destination`, or a statement that names its own target (`INSERT`, `UPDATE`, `DELETE`, `MERGE`, DDL). Also takes reads too large to return interactively. Returns `state: COMPLETE` when the write landed inline, or `SUBMITTED` with a `run_id` to poll. Never returns rows.
`query_dialect_analyze`	Report which SQL dialect a query reads as, and whether each engine (DuckDB, Bloom, Spark, Polars) can run it as written, needs a rewrite, or can’t run it at all - ranked most-viable-first with a 0-1 match score per engine. Parses only, so it’s cheap to call before committing to a query. Set `transpile_to` to get a rewrite back in `transpiled.sql`; show it to the user before running rather than substituting it silently. Syntax-only - it doesn’t know which tables or functions an engine actually has, so `query_run` with `explain: true` is still what decides routing. Backs the dialect badges in the lake editor.
`spark_sql_submit`	Submit a Spark SQL query under a job name and namespace you choose, with explicit driver and executor machine types. Use this when you need that control; `query_submit` names the job after the query and sizes compute automatically.

lake_query is gone. It pinned DuckDB and returned rows for reads and writes alike; query_run and query_submit replace it and route instead. See Query routing.

Saved query schedules

A schedule points at a saved query, so saved_queries_list/saved_queries_create are here too - without them there’s no query id to schedule.

Tool	Description
`saved_queries_list`	List saved queries, or look one up by exact name
`saved_queries_create`	Save a query under a name
`saved_queries_schedules_list`	Get a saved query’s schedule - interval, engine, destination, next run, last run status
`saved_queries_schedules_create`	Put a saved query on a recurring schedule - `15min`, `hourly`, or `daily` - running as an explicitly chosen `execution_principal_id`
`saved_queries_schedules_update`	Pause, resume, re-time, or change the engine or execution principal of a schedule
`saved_queries_schedules_delete`	Remove a schedule. Asks you to confirm before running.
`saved_queries_schedules_runs_list`	Run history for a schedule - status, timings, engine, errors

A saved query has at most one schedule; scheduling an already-scheduled query reschedules it in place rather than adding a second. Every new schedule needs an execution_principal_id - the connected user or an Application principal the user holds Describe and Manage grants on - and that principal’s roles govern the runs. saved_queries_schedules_create requires confirm: true - it starts recurring billable compute and overwrites its destination table on every run. See Scheduled queries with time-travel for what these schedules do.

Identity

Tool	Description
`identity_get`	Returns the authenticated identity and organization resolved by the MCP server
`system_health`	Returns MCP server health and timestamp

Catalogs and tables

Tool	Description
`catalogs_list`	List all available Iceberg catalogs and their tables
`catalogs_namespaces_list`	List namespaces in a catalog
`catalogs_tables_list`	List tables in a catalog or namespace
`catalogs_tables_metadata_get`	Read Iceberg table metadata - schema, partition specs, snapshots, location
`catalogs_tables_size_get`	Compute table size from Iceberg manifests, optionally scoped to a snapshot or partition
`catalogs_namespaces_create`	Create an Iceberg namespace in a catalog
`catalogs_tables_create`	Create an Iceberg table with a given schema
`catalogs_tables_drop`	Drop an Iceberg table. Asks you to confirm before running.
`catalogs_columns_add`	Add columns to an existing Iceberg table
`catalogs_columns_rename`	Rename a column in an Iceberg table
`catalogs_columns_drop`	Drop columns from an Iceberg table. Asks you to confirm before running.
`catalogs_tables_load`	Create a new Iceberg table from a staged or remote Parquet, CSV, or JSON file. Submits a Spark load run and returns a `run_id`; the table exists once the run reaches `COMPLETE`. CSV sources are read with the first row as column names and column types inferred from the values.
`catalogs_files_stage`	Stage a local data file (upload it with curl) for loading into a table with `catalogs_tables_load`

External connections

Tool	Description
`postgres_connections_list`	List registered Postgres connections - name, host, port, database, username. Credentials are never returned.
`postgres_tables_import`	Import a Postgres table into Iceberg with a partitioned, parallel Spark JDBC read against one exported MVCC snapshot. Returns a `run_id`; does not return rows.

BigQuery, Snowflake, and Postgres tables are queried through query_run as connection.schema.table - no source-specific query tool. Those queries always run on DuckDB.

Spark

Tool	Description
`spark_artifacts_list`	List uploaded PySpark scripts and JARs
`spark_artifacts_upload`	Upload a PySpark script or JAR as a versioned artifact
`spark_artifacts_get`	Fetch the source of a PySpark artifact by name and version
`spark_jobs_submit`	Submit a Spark job run for a named artifact
`spark_jobs_abort`	Abort a running Spark job. Asks you to confirm before running.

Runs and pipelines

Tool	Description
`jobs_runs_list`	List recent runs for a job by namespace and name
`jobs_runs_get`	Get full execution context for a job run - state, timestamps, I/O, datasets, warnings
`jobs_logs_get`	Get paginated logs for a job run, with optional text search and severity filter
`jobs_traces_get`	Get paginated OTel trace spans for a job run
`jobs_cost_get`	Get cost breakdown for a job run - vCPU-hours, GB-hours, cost per record
`pipelines_runs_list`	List runs for a pipeline with time range and state filters
`pipelines_runs_get`	Get full execution context for a pipeline run across all its job runs
`pipelines_cost_get`	Get aggregated cost across all job runs in a pipeline execution
`bigquery_cost_get`	Get cost breakdown for a BigQuery table - producing pipelines, query types, full-scan detection

Lineage

Tool	Description
`lineage_events_list`	List raw OpenLineage run events with time range, job, namespace, and state filters
`lineage_events_validate`	Validate a single OpenLineage run event against the core spec and oleander’s dataset naming conventions. Runs locally on the MCP server - nothing is stored, so it’s safe to call in a loop while an agent fixes an event. Backs the interactive validator at oleander.dev/ol-validate.
`jobs_lineage_get`	Get the lineage graph for a run - inputs, outputs, child runs, downstream consumers, schema
`lineage_columns_get`	Get column-level lineage for a dataset version - upstream sources and downstream dependents

Investigations

Tool	Description
`investigations_list`	List investigations for your organization
`investigations_get`	Get the full output of an investigation - telemetry gathered, root cause, remediation

Docs

Tool	Description
`docs_search`	Search these docs from inside the agent
`docs_pages_get`	Fetch a docs page by path

Registry listings

The server ships a server.json manifest and is listed where agents look for tools, so most clients can add it without a hand-written config.

Directory	Listing
MCP Registry	`dev.oleander/oleander`, published under a DNS-verified `oleander.dev` namespace
Smithery	All tools scanned, connect over OAuth
Aggregators	PulseMCP, Glama, and most client-side directories sync from the official registry

Two agent-readable surfaces are served from the site itself:

URL	What it is
`oleander.dev/llms.txt`	The index agents fetch by convention - connect commands and doc links
`oleander.dev/install.md`	One-shot setup instructions per client, safe to hand directly to any agent

Annotations

Every tool carries MCP annotations so clients can decide what needs confirmation:

readOnlyHint is true for anything that only reads. query_run is guarded to keep that promise - a statement that could mutate is rejected rather than run.
destructiveHint is true for drops and aborts.
Tools that start compute or change data take an explicit confirm argument on top of the annotation.

Confirming destructive tools

Four tools remove something that cannot be recovered from the agent’s side: catalogs_tables_drop, catalogs_columns_drop, saved_queries_schedules_delete, and spark_jobs_abort. On top of confirm: true, the server asks you directly before running any of them. When your client supports form elicitation, the first call returns a confirmation prompt instead of running. The prompt names exactly what is about to go - the fully qualified catalog.namespace.table and every column path, the schedule id, or the run id. Your client shows it to you and retries the call with your answer:

Accept with confirm: true runs the operation.
Decline or cancel returns an error to the agent and nothing is dropped, deleted, or aborted.

Clients that do not declare form elicitation skip the prompt and rely on the confirm argument and the destructiveHint annotation as before. That includes any client still on the 2025 protocol handshake and the in-app chat.

Getting Started

Platform

IAM

Connections

Integrations

Coding with agents

CLI

External Compute

MCP Tools Reference

Endpoint

Example workflow

Tools

Queries

Saved query schedules

Identity

Catalogs and tables

External connections

Spark

Runs and pipelines

Lineage

Investigations

Docs

Registry listings

Annotations

Confirming destructive tools

Editor setup

​Endpoint

​Example workflow

​Tools

​Queries

​Saved query schedules

​Identity

​Catalogs and tables

​External connections

​Spark

​Runs and pipelines

​Lineage

​Investigations

​Docs

​Registry listings

​Annotations

​Confirming destructive tools

​Editor setup

Endpoint

Example workflow

Tools

Queries

Saved query schedules

Identity

Catalogs and tables

External connections

Spark

Runs and pipelines

Lineage

Investigations

Docs

Registry listings

Annotations

Confirming destructive tools

Editor setup