--- 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. ## 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. ## 2. Add the MCP server The server is `https://oleander.dev/mcp`, over streamable HTTP with OAuth. Add it for the client you are running in: - Claude Code: `claude mcp add --transport http oleander https://oleander.dev/mcp` - Codex: `codex mcp add oleander --url https://oleander.dev/mcp` - OpenCode: `opencode mcp add oleander --url https://oleander.dev/mcp` - VS Code: `code --add-mcp '{"name":"oleander","type":"http","url":"https://oleander.dev/mcp"}'` - Cursor: give the user this link to click, [Add oleander to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=oleander&config=eyJuYW1lIjoib2xlYW5kZXIiLCJ0cmFuc3BvcnQiOiJzdHJlYW1hYmxlLWh0dHAiLCJ1cmwiOiJodHRwczovL29sZWFuZGVyLmRldi9tY3AifQ==), or add `{"mcpServers":{"oleander":{"url":"https://oleander.dev/mcp"}}}` to `.cursor/mcp.json` - Claude Desktop or claude.ai: the user adds a custom connector in Settings, Connectors, with the URL `https://oleander.dev/mcp` - Any other client: a remote server named `oleander` with the URL above If you cannot run commands yourself, show the user the line for their client. ## 3. Hand the sign-in to the user Tell the user exactly what to do, then wait until they say they are done: - Claude Code: run `/mcp`, choose `oleander`, and pick Authenticate. - Codex, Cursor, VS Code, and other clients: a browser window opens the first time the client connects. In Cursor, start it from the oleander entry in the MCP settings if it does not open by itself. 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. Either way, the next page asks them to allow access. After that, the browser hands control back to you. Some clients load a newly added server only in a new session. If oleander tools do not appear after the user signs in, ask them to restart or reload the agent, then read this file again and continue from step 4. ## 4. Verify the connection Call `identity_get`. Tell the user the connection works and which organization they are in. If it fails with an authentication error, go back to step 3. ## 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. Then take the matching path: - 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: call `catalogs_tables_load` with `from` set to the URL. - 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`. - Nothing yet: offer a public sample, one month of NYC taxi trips. Call `catalogs_tables_load` with `from` set to `https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-01.parquet`. 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. ## 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`). Tell the user the query now shows up at https://oleander.dev/app/overview. ## 7. Finish Summarize what is set up in two or three lines, 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.