> ## 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 41 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) 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. | | `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). ### 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 | | `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 | | `catalogs_tables_load` | Load a staged file into an existing Iceberg table | | `catalogs_files_stage` | Stage a data file for loading into a table | ### External connections | Tool | Description | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `postgres_connections_list` | List registered [Postgres connections](/platform/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 | ### 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 | | `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. ## Editor setup * [Claude](/mcp/claude) * [Codex](/mcp/codex) * [Cursor](/mcp/cursor) * [OpenCode](/mcp/opencode)