Using Ouro in Cursor and Claude

The assistant you already code with can work on Ouro directly. With the Ouro MCP server connected, Cursor or Claude can search for datasets, query them in SQL, run someone's API on your files, and publish what it finds to your team, all from the same chat where it edits your code.

This guide gets you connected, then walks through one real session from start to finish. Setup takes about five minutes.

Before you start

You need three things:

1. An Ouro account. Sign up if you don't have one.
2. An API key. Create one at Settings > API keys.
3. uv. The configs below launch the server with uvx, which downloads and runs ouro-mcp without a separate install. Python 3.10 or later is required.

Decide whose key to use. Everything the assistant creates is credited to the account that owns the key. Use your own key when the assistant is working for you and you review what it publishes. Give it a separate agent account when it should build its own reputation or run unattended.

Connect your client

Cursor

Add the server to ~/.cursor/mcp.json. That file is global, so the key stays out of your repositories and every project gets Ouro:

{
  "mcpServers": {
    "ouro": {
      "command": "uvx",
      "args": ["ouro-mcp"],
      "env": {
        "OURO_API_KEY": "your-api-key"
      }
    }
  }
}

Open Cursor Settings and find the MCP section. The ouro server should show a green status and list its tools. If it doesn't, toggle it off and on.

Claude Code

Register the server once for your user:

claude mcp add ouro --scope user --env OURO_API_KEY=your-api-key -- uvx ouro-mcp

Run claude mcp list to confirm it connects, or type /mcp inside a session.

To share the setup with your team without sharing a key, commit a project .mcp.json that reads the key from each person's environment:

{
  "mcpServers": {
    "ouro": {
      "command": "uvx",
      "args": ["ouro-mcp"],
      "env": { "OURO_API_KEY": "${OURO_API_KEY}" }
    }
  }
}

Claude Desktop

Open Settings > Developer > Edit Config, which opens claude_desktop_config.json, and add the same entry you'd use for Cursor. Quit and reopen Claude Desktop. The Ouro tools appear under the tools menu in the chat box.

Desktop apps don't always inherit your shell's PATH. If the server fails to start, replace "uvx" with the full path that which uvx prints.

Check the connection

Start with a question that only works if the connection works:

Who am I on Ouro, and which organizations and teams am I in?

The assistant calls get_me, get_organizations, and get_teams, and answers with your username and a list of teams. Keep that list handy. You'll use it in the next step.

Tell it where to publish

Every asset on Ouro belongs to one organization and one team. If the assistant doesn't choose, its work lands in the catch-all All team, where few people will see it. It also needs to know that posts are public unless it says otherwise.

Put those defaults where the assistant reads them every session: AGENTS.md or a rule in .cursor/rules/ for Cursor, and CLAUDE.md for Claude Code.

## Ouro
 
- Publish to the `materials` team in the Acme Lab org:
  org_id `…`, team_id `…`. Ask before publishing anywhere else.
- Create posts and datasets as `private` drafts. I'll publish them.
- Link every asset you mention with typed links like `[results](dataset:<uuid>)`,
  and embed route runs with their `actionId` so readers can see the exact run.
- Ask before any tool that spends money: `execute_route` on a paid route,
  `unlock_asset`, `send_money`, `add_funds`.

Replace the IDs with the ones from the connection check. With that in place, a request like "write this up" produces a private draft in the right team, not a public post in All.

A first session

This session takes one question from search to published report. Each step is a single prompt. You don't need to name tools; the assistant reads their descriptions and picks.

1. Find the data

Find public datasets on Ouro about thermoelectric materials. For the most promising one, show me its columns and five sample rows.

The assistant runs search_assets, then reads the schema and queries a sample with query_dataset. Queries are read-only PostgreSQL, so you can push it further in plain language: "Which ten compounds have the highest ZT above 600 K?" becomes SQL with an ORDER BY and a LIMIT, and only ten rows come back into the chat.

2. Work on it locally

This is where an editor beats a chat window. When the question needs more than SQL, have the assistant download the data and work on it in your project:

Download that dataset and write a script in analysis/ that fits ZT against carrier concentration for each material family. Run it and plot the fits.

download_asset writes a CSV to disk and returns the path, not the contents. Your assistant then reads, scripts, and plots it with the same tools it uses on your code, and the full table never has to fit in its context window.

3. Run an API on your own files

Ouro can tell the assistant which APIs accept an asset it's already holding:

Upload structures/Bi2Te3.cif to my team as a private file. Then find routes that accept it and run the best one that predicts thermal conductivity. Do a dry run first and tell me what it costs.

The assistant uploads with create_file, lists candidates with get_compatible_routes, and validates the call with execute_route(..., dry_run=true) before spending anything. When the real run finishes, it gets back a short summary, the IDs of any output assets, and an actionId that identifies this exact run. Long runs keep going after the call returns; the assistant checks back with get_action, and reads get_action_logs if something fails.

4. Chart it

Save a view on the original dataset: a scatter plot of ZT against temperature, one series per material family.

write_dataset_view takes that description, writes the SQL and chart config, and pins the chart to the dataset. See Datasets > Views for how views work.

5. Publish the result

Write this up as a post: what we asked, the chart, the route run, and what we learned. Link everything.

Because of your AGENTS.md, the assistant creates a private draft in your team. The post uses extended markdown: the saved view is embedded, the route is embedded with its actionId so readers see the run's status and outputs, and the dataset and uploaded file are linked. Open it, edit what you like, and publish.

Anyone reading the post can click through to the data, the exact run, and the file it ran on. That trail is what makes the result worth building on. The data reports guide covers writing these posts in depth.

Resources and prompts

Beyond tools, the server exposes read-only resources that clients can attach as context without a tool call:

It also ships a quest_authoring_guide prompt that walks the assistant through drafting a clear, reviewable quest. In Claude Code it appears as a slash command; in Claude Desktop, under the attachments menu.

Keep spending under your control

Most tools are free: searching, reading, querying, and publishing. Only a few move money: running a paid route, unlock_asset, send_money, and add_funds. Leave approval on for those even if you auto-approve the rest.

• Cursor asks before each tool call unless you've allowlisted the tool. Allowlist read tools like search_assets and query_dataset freely.
• Claude Code lets you pre-approve tools in your permission settings by name, like mcp__ouro__search_assets. Pre-approve read tools, not the ones above.

execute_route(..., dry_run=true) validates a call without running it, and get_balance shows what the account can spend.

Troubleshooting

The server doesn't start. Run uvx ouro-mcp in a terminal. If it waits silently for input, the server works and the problem is the client's config or PATH.

Tools are missing or outdated. uvx caches packages. Use "args": ["ouro-mcp@latest"] to pick up new releases, then reload the client.

Every call fails with an auth error. The key is missing from the server's env block or was copied with extra characters. Clients don't read your shell profile, so exporting the key in a terminal isn't enough.

Creating an asset fails on a team. The team may only accept assets made in the web app. MCP counts as the API, so check agent_can_create in get_teams and pick another team. See Teams.

Someone can't see what the assistant published. Private assets stay private even when you mention or embed them. Ask the assistant to share it with share_asset, or publish it.

Next steps

• MCP interface: every tool, plus hosted and local modes
• Publishing data reports: posts that show their work
• Building Ouro services with a coding agent: from model to live API without leaving the editor
• Running a long-lived agent: when the assistant should work on its own schedule