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

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

1
{
2
  "mcpServers": {
3
    "recursiv": {
4
      "command": "npx",
5
      "args": ["-y", "@recursiv/mcp"],
6
      "env": { "RECURSIV_API_KEY": "sk_live_xxx" }
7
    }
8
  }
9
}

Full setup and the tool list: MCP.

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:

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.

1
import { Recursiv } from '@recursiv/sdk';
2
3
const r = new Recursiv(); // reads RECURSIV_API_KEY

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

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

3. Run an agent on any model.

1
const { data: agent } = await r.agents.create({
2
  project_id: project.id,
3
  name: 'Researcher',
4
  username: 'researcher', // required, unique within the project
5
  model: 'claude-sonnet-4-6', // any model you choose
6
  system_prompt: 'Research markets and cite sources.',
7
});
8
9
for await (const chunk of r.agents.chatStream(agent.id, {
10
  message: 'Size the market for home management software',
11
})) {
12
  process.stdout.write(chunk.delta ?? '');
13
}

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

1
await r.databases.ensure({ project_id: project.id, name: 'main' });
2
const { data: rows } = await r.databases.query({
3
  project_id: project.id,
4
  sql: 'select now() as time',
5
});
6
7
const { data: run } = await r.sandbox.execute({
8
  code: 'console.log(1 + 1)',
9
  language: 'typescript',
10
});

5. Ship it to a URL.

1
// No repo yet? Scaffold one server-side. Templates: 'nextjs' | 'expo'.
2
const { data: repo } = await r.github.createFromTemplate({
3
  template: 'nextjs',
4
  name: 'my-app',
5
});
6
await r.projects.update(project.id, { repo_url: repo.repo_url });
7
8
const { data: deployment } = await r.projects.deploy(project.id, {
9
  branch: 'main',
10
  type: 'production',
11
});
12
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:

1
const r = new Recursiv({ anonymous: true });
2
const { data, meta } = await r.sandbox.execute({
3
  code: 'console.log("hello from recursiv")',
4
  language: 'typescript',
5
});
6
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.

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.
• 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, the entire docs in one file
• SDK Reference, every resource and method
• Recipes, copy-paste snippets for common tasks
• MCP, the full tool list
• API Reference, the REST surface, for any language or runtime