Skip to main content

Automate with agents

You just walked the whole path by hand — query the warehouse, ingest a source, model it, build a notebook, and publish and share the result. A hosted agent connected over MCP can run that same path for you.

This page is the shape of that automation: how to connect, how the work is structured, and the one contract that keeps it honest — verify each step before treating it as done.

Connect an agent over MCP​

Everything an agent needs is exposed over the OSO MCP server. Point your client at https://mcp.oso.xyz/mcp over Streamable HTTP with a bearer token, and it picks up the same tools you've been using — execute_sql to query, plus tools to ingest data, build UDMs, and publish notebooks.

Connect over MCP is the complete setup page: server URL and transport, generating an API key, and per-client config for Claude Code, Codex CLI, and OpenClaw. Get connected there first, then come back.

The workflow shape​

An agent doesn't do this in one shot. The pipeline is a sequence of stages, and a good run works through them in order, carrying state forward:

  1. Query — explore what's already in the warehouse before adding anything.
  2. Ingest — bring in the missing source as a queryable table.
  3. Model — shape raw tables into the UDMs your question actually needs.
  4. Build — assemble a notebook on top of those models.
  5. Publish — persist and share the result.

Each stage depends on the one before it, and several of them are asynchronous — materializing a model or publishing a notebook kicks off a run that finishes later. So the agent tracks where it is, what it has built, and what it's still waiting on, rather than firing everything at once and hoping.

The manual tutorials linked above are the reference for what happens inside each stage. Automation doesn't replace them — it runs them for you, in that order.

Verify in the loop​

This is the part that matters most, and the part a one-shot script gets wrong.

Materializing a model and publishing a notebook are asynchronous: the tool call returns a run, not a finished result. The run can still fail — a bad column, a query that times out, a notebook cell that errors on execution. So after every step that starts a run, the agent should:

  1. Poll the run to completion — GetRun reports whether it succeeded, failed, or is still going.
  2. Verify the result before moving on. For a model, confirm it materialized and the data looks right. For a notebook, verify it visually — render it and look at the charts, don't just check that the run status is green. A notebook can execute cleanly and still show an empty chart or a broken axis.
  3. Only then treat the step as done and move to the next stage.

The unhappy path​

Runs fail. That's expected, and it's why the loop exists.

When GetRun comes back failed, the agent reads the error, fixes the cause — a column name, a join, a filter — and re-runs, rather than pressing on with a broken artifact underneath it. The same goes for a notebook that materializes but looks wrong on inspection: that's a failure too, even if the run status is green. Nothing downstream is trustworthy until the current step actually verifies.

Get the connection right, keep the stages in order, and hold the verify-in-loop contract, and an agent can take a question from raw data to a published notebook the same way you just did by hand.

What's next​

Deep Research goes a step further — pointing an agent at an open-ended question across all of your connected data and getting back a grounded, cited report.