> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recursiv.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recursiv.io/_mcp/server.

# Use Recursiv with your coding agent

Most people never read these docs. Their coding agent does. This page gets an
agent from zero to building on Recursiv in one step, then gives it the mental
model and the handful of patterns it needs to do real work.

If you are an agent reading this: start with [The five things you need](#the-five-things-you-need-to-know).

## The fastest path: give your agent the docs

Every page on this site is also published as plain text an agent can read in one
fetch:

* `https://docs.recursiv.io/llms.txt`, the map: what Recursiv is and every page link.
* `https://docs.recursiv.io/llms-full.txt`, the whole documentation as a single file.

Paste either URL into Claude Code, Cursor, or any agent and tell it to read the
page. That is enough for it to understand the platform and start writing correct
code.

## Connect over MCP

MCP gives an agent native tool access to Recursiv: create projects, run agents,
query databases, deploy, all as typed tools. One config, then the agent calls
Recursiv directly instead of writing HTTP.

**Claude Code**

```bash
claude mcp add recursiv -e RECURSIV_API_KEY=sk_live_xxx -- npx -y @recursiv/mcp
```

**Cursor, Windsurf, Claude Desktop**, add to the MCP config file:

```json
{
  "mcpServers": {
    "recursiv": {
      "command": "npx",
      "args": ["-y", "@recursiv/mcp"],
      "env": { "RECURSIV_API_KEY": "sk_live_xxx" }
    }
  }
}
```

Full setup and the tool list: [MCP](/guides/ai-tools/mcp-claude-cursor).

## A primer prompt to paste

Drop this into an agent's system prompt or the top of a task to teach it the
rules before it writes a line:

```text
You are building on Recursiv, the platform for building, running and governing
autonomous agents. The whole backend is one SDK: @recursiv/sdk.

Rules:
- Construct the client once: const r = new Recursiv(). It reads RECURSIV_API_KEY.
- Almost everything hangs off a project. Create one first and reuse project.id
  (a UUID) everywhere a project_id is needed.
- Reads return { data }. Paginated reads return { data, meta }.
- Use any model. Recursiv is model agnostic; pass the model you want on the agent.
- Do not invent methods. If you are unsure a method exists, read
  https://docs.recursiv.io/llms-full.txt or the SDK reference before calling it.

Install: npm install @recursiv/sdk
```

## The five things you need to know

Everything else is a variation on these. All five are real, current SDK calls.

**1. One client, one key.**

```typescript
import { Recursiv } from '@recursiv/sdk';

const r = new Recursiv(); // reads RECURSIV_API_KEY
```

**2. Work lives in a project. Create one, keep the id.**

```typescript
const { data: project } = await r.projects.create({ name: 'my-app' });
// project.id is a UUID. Use it everywhere a project_id is needed.
```

**3. Run an agent on any model.**

```typescript
const { data: agent } = await r.agents.create({
  project_id: project.id,
  name: 'Researcher',
  username: 'researcher', // required, unique within the project
  model: 'anthropic/claude-sonnet-4.6', // any model you choose
  system_prompt: 'Research markets and cite sources.',
});

for await (const chunk of r.agents.chatStream(agent.id, {
  message: 'Size the market for home management software',
})) {
  process.stdout.write(chunk.delta ?? '');
}
```

**4. Give it a database, storage, and a sandbox.**

```typescript
await r.databases.ensure({ project_id: project.id, name: 'main' });
const { data: rows } = await r.databases.query({
  project_id: project.id,
  sql: 'select now() as time',
});

const { data: run } = await r.sandbox.execute({
  code: 'console.log(1 + 1)',
  language: 'typescript',
});
```

**5. Ship it to a URL.**

```typescript
// No repo yet? Scaffold one server-side. Templates: 'nextjs' | 'expo'.
const { data: repo } = await r.github.createFromTemplate({
  template: 'nextjs',
  name: 'my-app',
});
await r.projects.update(project.id, { repo_url: repo.repo_url });

const { data: deployment } = await r.projects.deploy(project.id, {
  branch: 'main',
  type: 'production',
});
console.log(deployment.deployment_url);
```

## Try it with no account

An agent can prove the platform works before anyone signs up. The anonymous
sandbox needs no key:

```typescript
const r = new Recursiv({ anonymous: true });
const { data, meta } = await r.sandbox.execute({
  code: 'console.log("hello from recursiv")',
  language: 'typescript',
});
console.log(data.output, meta.remaining_executions);
```

Ten anonymous executions per IP per day. To go further, an agent can sign up and
mint its own key programmatically. See [Authentication](/guides/start-here/auth-api-keys#autonomous-onboarding-for-agents).

## Conventions an agent should not get wrong

* **Project ids are UUIDs.** Always use the `id` the API returns, never the name.
* **Responses are enveloped.** Single reads return `{ data }`, lists return `{ data, meta }` with pagination in `meta`.
* **Keys are scoped.** A key can be all-orgs, select-orgs, or bound to one org. Cross-org work needs a personal or select-orgs key. See [Auth & API keys](/guides/start-here/auth-api-keys).
* **Model agnostic.** Set `model` per agent. Swap it anytime. Nothing is locked to one provider.
* **Deploys need a linked repo.** A project must have a `repo_url` before `projects.deploy`, or it fails with "Project has no linked repository."

## Where to send your agent next

* [llms-full.txt](https://docs.recursiv.io/llms-full.txt), the entire docs in one file
* [SDK Reference](/sdk/setup/installation-configuration), every resource and method
* [Recipes](/recipes/cookbook/agents), copy-paste snippets for common tasks
* [MCP](/guides/ai-tools/mcp-claude-cursor), the full tool list
* [API Reference](/api-reference), the REST surface, for any language or runtime