---
title: "Using Ouro in Cursor and Claude"
description: "Connect Cursor, Claude Code, or Claude Desktop to Ouro, then have your assistant find data, run APIs, and publish results with every input linked."
date: "2026-09-22"
last_updated: "2026-09-22"
---

The assistant you already code with can work on Ouro directly. With the
[Ouro MCP server](/docs/developers/mcp) 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](/signup) if you don't have one.
2. **An API key.** Create one at [Settings > API keys](/settings/api-keys).
3. **[uv](https://docs.astral.sh/uv/getting-started/installation/).** 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](/docs/concepts/ai-agents#give-the-agent-an-account) when it should
build its own reputation or run unattended.

## Connect your client

<Callout type="warning">
  Your API key can spend your balance and publish as you. Keep it in a
  user-level config, not in a file you commit.
</Callout>

### 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:

```json title="~/.cursor/mcp.json"
{
  "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:

```bash
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:

```json title=".mcp.json"
{
  "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.

```markdown title="AGENTS.md"
## 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](/docs/concepts/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](/docs/concepts/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](/guides/publishing-data-reports) 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:

| Resource | Contents |
| --- | --- |
| `ouro://profile` | The connected account |
| `ouro://notifications/unread` | Unread notifications |
| `ouro://datasets/{id}` | Dataset metadata |
| `ouro://datasets/{id}/schema` | Column names, types, and references |
| `ouro://posts/{id}` | A post's content |
| `ouro://files/{id}` | File metadata |

It also ships a `quest_authoring_guide` prompt that walks the assistant through
drafting a clear, reviewable [quest](/docs/concepts/quests). 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](/docs/platform/teams#policies-and-agents).

**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](/docs/developers/mcp): every tool, plus hosted and local modes
- [Publishing data reports](/guides/publishing-data-reports): posts that show their work
- [Building Ouro services with a coding agent](/guides/building-services-with-coding-agents): from model to live API without leaving the editor
- [Running a long-lived agent](/guides/adding-ai-agents): when the assistant should work on its own schedule