---
name: oleander-setup
description: Connect this agent to oleander over MCP, have the user sign in (which creates a free account if they have none), load their first dataset, and run a first query on it. Use when the user asks to set up, connect, or try oleander.
---

# Set up oleander

oleander is a data warehouse your agent works in directly: upload files, connect databases, run SQL, and build on the results, all through one MCP server. This playbook takes the user from nothing to a first query on their own data.

It works whether or not the user has an oleander account. The sign-in in step 3 creates one for anyone who is new, so never ask whether they have signed up.

Work through the steps in order, and tell the user in one short line what each step is doing.

## How to work

- Do each step yourself when you have terminal or file access. Pause only for things the user must do: signing in, approving a command, or a click in an app you cannot control. Do not hand the user commands to copy when you can run them.
- If a command fails because of your sandbox, such as blocked network access or a read-only config file, first ask the user to approve running it outside the sandbox if your client allows that. Only if that is not possible, give the user the exact command to run in their own terminal.
- If a step is still blocked, note why and continue with the steps that do not depend on it. Step 7 reports what was blocked.
- Report only what you verified. Do not say something is connected, loaded, or working until a tool call confirms it.

## Rules

- The user signs in themselves, in their own browser. Never automate the browser, and never ask for a password, API key, or token in chat.
- Never ask for database credentials in chat. The user adds database connections in the oleander app.
- Use the organization the sign-in gives you. Do not create other accounts or organizations.
- `query_run` only reads. Ask before any write beyond loading the first table together.
- The free Hobby plan needs no credit card. Only bring up billing if a tool returns a billing error.

## 1. Check for an existing connection

If oleander tools such as `identity_get` are already available, call `identity_get`. If it succeeds, skip to step 4.

Otherwise, before adding anything, check whether oleander is already configured in your client: run its list command (`claude mcp list`, `codex mcp list`, or `opencode mcp list`), or read its MCP config file. If an `oleander` server is already there, do not add it again; go to your client's section in step 2 and continue from its sign-in step. When you edit an MCP config file, merge the `oleander` entry into it and leave every other server and setting as it is.

## 2. Connect your client and sign in

The server is `https://oleander.dev/mcp`, over streamable HTTP with OAuth. Follow the section for the client you are running in. Step 3 describes the browser page every client opens for sign-in.

### Claude Code

1. Add the server for this project:

   ```sh
   claude mcp add --scope project --transport http oleander https://oleander.dev/mcp
   ```

   This writes the server to `.mcp.json` in the project folder, so anyone who opens the project in Claude Code gets oleander too.

2. Restart. A server added during a session does not appear in that session, not even in `/mcp`, until Claude Code restarts, and `/mcp reconnect` does not pick it up either. Send the user only the restart steps, and nothing about sign-in or accounts yet: type `/exit`; run `claude --continue` in the same terminal and folder, which brings this conversation back; approve `oleander` when Claude Code asks about the new server in `.mcp.json`; then type `continue` so you can pick up from here.
3. Sign in. Once the user is back, ask them to run `/mcp`, choose `oleander`, and pick Authenticate, then explain the browser page as in step 3.

If the server was already configured when this session started, skip straight to sign-in.

### Codex

1. Add the server, then sign in:

   ```sh
   codex mcp add oleander --url https://oleander.dev/mcp
   codex mcp login oleander
   ```

   `codex mcp add` may open the browser by itself; if it does, `codex mcp login` is not needed. Codex's default sandbox usually blocks both commands, because they need network access and write to `~/.codex/config.toml`. Ask the user to approve running them outside the sandbox, or to run them in their own terminal.

2. Restart. Codex loads MCP servers only when it starts, so ask the user to exit and run `codex resume --last` in the same terminal, which brings this conversation back, then type `continue`.

### Cursor

1. Give the user this link to click: [Add oleander to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=oleander&config=eyJuYW1lIjoib2xlYW5kZXIiLCJ0cmFuc3BvcnQiOiJzdHJlYW1hYmxlLWh0dHAiLCJ1cmwiOiJodHRwczovL29sZWFuZGVyLmRldi9tY3AifQ==). Or merge `{"mcpServers":{"oleander":{"url":"https://oleander.dev/mcp"}}}` into `.cursor/mcp.json`.
2. Sign in. A browser window opens the first time Cursor connects. If it does not, ask the user to start it from the oleander entry in Cursor's MCP settings.
3. If oleander tools still do not appear, ask the user to turn the oleander server off and on in the MCP settings. Reload the window only if that does not work.

### VS Code

1. Add the server:

   ```sh
   code --add-mcp '{"name":"oleander","type":"http","url":"https://oleander.dev/mcp"}'
   ```

2. Sign in. A browser window opens the first time VS Code connects to the server.
3. If oleander tools do not appear, ask the user to start the server from the MCP server list. Reload the window only if that does not work.

### OpenCode

1. Add the server:

   ```sh
   opencode mcp add oleander --url https://oleander.dev/mcp
   ```

2. Sign in. A browser window opens the first time OpenCode connects.

### Claude Desktop or claude.ai

The user adds a custom connector in Settings, Connectors, with the URL `https://oleander.dev/mcp`, then connects it, which opens the sign-in page.

### Any other client

Add a remote server named `oleander` with the URL above. Most clients open the sign-in page the first time they connect. If oleander tools do not appear after sign-in, refresh the client's MCP server list first; restart or reload the client only if that does not load them. If the client loses this conversation on restart, read this file again and continue from step 4.

## 3. The sign-in page

The browser shows a page titled "Connect (your client) to oleander". Explain both cases so the user knows what to expect:

- New to oleander: GitHub, Google, or an email link creates a free account. There is no separate signup.
- Already signed up: the same buttons sign in.

A new account then sets up its organization in two short steps: a name (a suggestion is filled in), then storage. oleander managed storage is selected and works right away; their own S3 bucket is for anyone who needs data to stay in their AWS account. Do not ask them to choose in chat, and do not make the choice for them.

Either way, the next page asks them to allow access. After that, the browser hands control back to you. Wait until the user says they are done.

## 4. Verify the connection

Call `identity_get`. Tell the user the connection works and which organization they are in. If oleander tools are not available, the client has not loaded the server yet; go back to your client's section in step 2. If `identity_get` fails with an authentication error, the user has not finished signing in; repeat your client's sign-in step.

## 5. Load the first dataset

Ask one question: what data do they want to work with? Ask for a table name too; never invent one. Offer the options in the order below, with the sample first and marked as recommended. Then take the matching path:

- No data of their own (recommended): load a public sample, one month of NYC taxi trips. Download `https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-01.parquet` to a local temporary file using curl with `--fail`, `--location`, and `--output`. Then call `catalogs_files_stage`, upload the local file with curl exactly as its description says, and call `catalogs_tables_load` with `from` set to the returned staging `destination`.
- A file on this machine (CSV, JSON, or Parquet): call `catalogs_files_stage`, upload the file with curl exactly as its description says, then call `catalogs_tables_load` with the returned `destination`. Parquet loads most reliably, so if you can convert a CSV or JSON file locally first (DuckDB, Polars, or pandas), do.
- A public URL: download the file locally using curl with `--fail`, `--location`, and `--output`. Then call `catalogs_files_stage`, upload the local file with curl exactly as its description says, and call `catalogs_tables_load` with `from` set to the returned staging `destination`.
- A Postgres, MySQL, or MongoDB database: send the user to https://oleander.dev/app/settings/lake to add the connection themselves. Then find it with `postgres_connections_list` (or the MySQL or MongoDB equivalent) and either query it live with `query_run`, or copy a table into the lake with `postgres_tables_import`.

Loads and imports run as background jobs. Poll `jobs_runs_get` with the returned run id until the run completes, and read `jobs_logs_get` if it fails. Once `jobs_runs_get` returns the run's pipeline, give the user a link to watch the run, built from `pipeline.id` and the full run id:

`https://oleander.dev/app/pipelines?pipelineId=<pipeline.id>&traceView=true&runId=<run_id>`

## 6. Run the first query

Use `query_run` to answer something real about the new table: a row count and a small sample, then one question the user cares about. Show the result as a short table and mention which engine ran it (from `engine_decision`). If the response includes a `run_id`, call `jobs_runs_get` with it and link the user to the query's trace with the same URL as in step 5. Otherwise, tell the user the query now shows up at https://oleander.dev/app/overview.

## 7. Finish

Report what is set up in this format, filling in only what a tool call confirmed. For anything that did not happen, write what blocked it:

```text
oleander setup
MCP: <connected | blocked: reason>, <client>, configured in <.mcp.json | ~/.codex/config.toml | client settings>
Organization: <organization from identity_get>
First table: <catalog.namespace.table | not loaded: reason>
Run trace: <link from step 5 | none>
First query: <ran on engine | not run: reason>
```

Then suggest what to try next:

- "Save this query and run it every hour."
- "Join this table with my Postgres orders."
- "Show me the lineage and cost of that query."

More: per-client setup details at https://oleander.dev/install.md, and full documentation at https://docs.oleander.dev.
