---
title: "Use MainSDK with your coding agent"
description: "Use MainSDK from Claude Code, Cursor, Codex or any MCP agent, with AGENTS.md rules, the MCP server, your actions as tools and the migration skill."
section: "getting-started"
canonical: "https://mainsdk.dev/docs/getting-started/with-your-agent"
updated: "2026-10-28"
---

# Use MainSDK with your coding agent

> Use MainSDK from Claude Code, Cursor, Codex or any MCP agent, with AGENTS.md rules, the MCP server, your actions as tools and the migration skill.

Canonical: https://mainsdk.dev/docs/getting-started/with-your-agent · Updated: 2026-10-28

> **Get the MainSDK skill.** `SKILL.md` plus a reference of every interface teaches your agent the MainSDK rules. Install it by copying the folder to `.claude/skills/mainsdk/`; later, `npx mainsdk init` will do it (planned). Download: [SKILL.md](https://mainsdk.dev/skill/SKILL.md) and [references/interfaces.md](https://mainsdk.dev/skill/references/interfaces.md).

You now have an app that passes `mainsdk check`. Most of its next changes will probably come from a coding agent. MainSDK is built for that: your agent calls short interfaces instead of writing provider code, reads every failure with its fix, and works through the same gates you do. Free checks run on your own agent and keys.

MainSDK is pre-release; the commands on this page are the planned design and do not run yet. The CLI and `init` are planned for 0.2, the MCP server's `check` and `logs` tools with them, and the migration skill for 0.5.

## What init sets up

`mainsdk init` detects your agent and writes three things:

| File or setting | What it does |
| --- | --- |
| `AGENTS.md` | A MainSDK section, between markers, with the rules: call interfaces, keep keys as `secret:` references, run `mainsdk check` before a pull request |
| `CLAUDE.md` | The same section for Claude Code |
| MCP server registration | Connects your agent to the MainSDK MCP server, so it can run checks, read logs and drive adoption |

If those files already exist, `init` appends its section between markers and leaves the rest alone.

## Skills and rules: what lives where

There are two different things, in two different places.

| What | Path | Purpose | Agents |
| --- | --- | --- | --- |
| The MainSDK skill (general) | `.claude/skills/mainsdk/SKILL.md` | How to build with interfaces: call shapes, rules, what to run | Claude Code. Other agents reach it from the `AGENTS.md` section |
| The migration skill | `.claude/skills/mainsdk-adopt/SKILL.md` | Bringing an existing app onto MainSDK, one pull request at a time | Claude Code |
| The migration skill, as a rule | `.cursor/rules/mainsdk-adopt.mdc` | The same steps | Cursor |
| The `AGENTS.md` section | `AGENTS.md` | The short rules, and a pointer to the skill | Cursor, Codex and any agent that reads `AGENTS.md` |

If the general skill isn't in `.claude/skills/mainsdk/`, copy its folder there. Everything else is written by `mainsdk init` or fetched by the agent.

## Per agent

Claude Code:

```text
Reads:      CLAUDE.md and AGENTS.md
MCP:        registered by mainsdk init
Skills:     .claude/skills/mainsdk/ (general), .claude/skills/mainsdk-adopt/ (migration)
```

Cursor:

```text
Reads:      AGENTS.md
MCP:        registered by mainsdk init
Rules:      .cursor/rules/mainsdk-adopt.mdc (migration)
```

Codex:

```text
Reads:      AGENTS.md
MCP:        add the MainSDK MCP server like any MCP server (below)
Skill:      the AGENTS.md section
```


Any MCP-capable agent works the same way: it reads `AGENTS.md` and connects to the MCP server.

### Register the server by hand

For agents `init` doesn't detect, register the server yourself. The command that starts the server is `mainsdk mcp`. This is the planned command; no flags are specified yet.

Claude Code:

```bash
claude mcp add mainsdk -- npx mainsdk mcp
```

Cursor and other agents that read a JSON config (in Cursor, `.cursor/mcp.json`):

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "mainsdk": { "command": "npx", "args": ["mainsdk", "mcp"] }
  }
}
```

For Codex or any other client, use that client's MCP settings with the same command (`npx`) and arguments (`mainsdk mcp`). Run it from your project root so the server reads your `main.yaml`.

## The MCP server

The MainSDK MCP server gives your agent the same tools you have on the command line, with structured results it can act on:

- **Check:** run the gates and get findings with code, file, line and fix. An agent that gets `MAIN-DATA-0007` reads the fix (`Scope the query with db.orders.for(session.user)`) and applies it.
- **Logs and errors:** read local logs and errors in RFC 9457 shape with the trace id, so it can find the cause without guessing.
- **Adopt:** `adopt.scan`, `adopt.report`, `adopt.lock`, `adopt.plan_module`, `adopt.verify_module` and `adopt.finish`, used by the migration skill.

Everything runs locally. Nothing is sent to MainSDK Cloud unless you run `mainsdk login` and opt in.

A typical loop, in your words to the agent:

```text
You:   Add an endpoint that lists the signed-in user's orders.
Agent: (writes app/api/orders/route.ts with db.orders.for(session.user).list())
Agent: (runs check through MCP) all gates passed
Agent: Done. The route requires sign-in and only returns the user's own orders.
```

## Prompts that work

Ten copy-paste prompts, each ending with the check to run and what a pass looks like, are on [Prompts that work](https://mainsdk.dev/docs/agents/prompts).

## Your app's actions as agent tools

Your own app can serve agents too. Mark an action with `mcp: true` and it becomes an MCP tool on your app, behind the same identity, owner scope, rate limits and policy as the HTTP route.

```ts title="app/actions/refund-order.ts"
import { action, db, pay } from "mainsdk";
import { s } from "mainsdk/schema";

export const refundOrder = action({
  name: "orders.refund",
  intent: "Refund an order the signed-in user owns",
  input: s.object({ orderId: s.string(), reason: s.string() }),
  risk: "destructive",          // an agent must get the person's yes first
  mcp: true,
  run: async ({ input, user }) => {
    const order = await db.orders.for(user).get(input.orderId);
    return pay.refund(order.paymentId, { reason: input.reason });
  },
});
```

```yaml title="main.yaml"
mcp:
  expose: [orders.refund, orders.list]
  confirm: { write: true, destructive: true }
  auth: { issuer: auth, scopes: [orders:read, orders:refund], token-ttl: 10m }
```

Only marked actions are exposed, and destructive ones always wait for a person's yes. To limit an agent that calls your app, give it a budget in `main.yaml`:

```yaml title="main.yaml"
agents:
  support-bot:
    budget: { spend: $5/day, calls: 500/day }
    approve: { risk: destructive, spend-over: $1 }
```

A call over budget fails before it runs, and a step over `spend-over` waits for a person. See the [glossary](https://mainsdk.dev/docs/reference/glossary) for budget.

 [Actions and MCP](https://mainsdk.dev/docs/concepts/actions-and-mcp) covers confirmation, signed tool descriptions and agent tokens; the API is on [Actions and agent tools](https://mainsdk.dev/docs/interfaces/action).

## The migration skill

For an app you already have, the migration skill lets your agent bring it onto MainSDK one pull request at a time, with MainSDK's gates verifying every step. Ask your agent:

```text
Bring this app onto MainSDK with the mainsdk-adopt skill.
```

The migration skill lives at `.claude/skills/mainsdk-adopt/` (see the table above). It scans the app, reports the gaps by risk, locks your key flows, migrates one module per pull request and finishes with a launch report. The same steps run without an agent as `mainsdk adopt`, which the next page walks through.

## Next

- [Adopt an existing app](https://mainsdk.dev/docs/getting-started/existing-app)
- [Actions and MCP](https://mainsdk.dev/docs/concepts/actions-and-mcp)
- [Errors and problem details](https://mainsdk.dev/docs/reference/errors)