Use MainSDK with your coding agent

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:

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.

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

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

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

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:

claude mcp add mainsdk -- npx mainsdk mcp

Cursor and other agents that read a JSON config (in Cursor, .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:

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.

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.

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 });
  },
});

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:

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 for budget.

Actions and MCP covers confirmation, signed tool descriptions and agent tokens; the API is on Actions and agent tools.

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:

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
• Actions and MCP
• Errors and problem details