> ## 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. # MCP Tools Reference > All 50 tools exposed by the oleander MCP server. 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](https://oleander.dev/app/settings/api-keys) via `Authorization: Bearer`. Most MCP clients handle this automatically after the OAuth flow. The server is published to the [official MCP registry](#registry-listings) 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](/platform/query-routing/overview) 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](/platform/query-routing/transpilation) 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](/platform/query-routing/overview). ### 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](#confirming-destructive-tools) 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](/platform/compute/duckdb#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](#confirming-destructive-tools) 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](#confirming-destructive-tools) 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](/connections/postgres) - 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](#confirming-destructive-tools) 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](https://openlineage.io/docs/spec/naming/). 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](https://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](https://registry.modelcontextprotocol.io) | `dev.oleander/oleander`, published under a DNS-verified `oleander.dev` namespace | | [Smithery](https://smithery.ai/servers/peter-5dn5/oleander) | 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`](https://oleander.dev/llms.txt) | The index agents fetch by convention - connect commands and doc links | | [`oleander.dev/install.md`](https://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](https://modelcontextprotocol.io/specification/2026-07-28/client/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. ## Editor setup * [Claude](/mcp/claude) * [Codex](/mcp/codex) * [Cursor](/mcp/cursor) * [OpenCode](/mcp/opencode) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.