Reference

Docs

Install the CLI, point Claude at the hosted MCP server, and deploy. This page covers setup, the grains.toml shape, and how pricing and receipts work.

01 — Install the CLI

grains CLI

Scaffolds new agents and runs them locally before you deploy.

pip install grains-cli

grains init my-agent              # scaffold grains_app.py + grains.toml
grains init my-agent --template crewai
grains init my-agent --template langchain
grains init my-agent --template langgraph

cd my-agent
grains dev                        # run it locally on :8787

Once it's deployed and priced, call it and pay via x402 from the CLI:

grains pay https://agents.grains.run my-agent \
  --text "summarize https://grains.run" \
  --key "$GRAINS_PAYER_KEY"

grains verify receipt.json         # verify a receipt offline

02 — Configure the MCP server

Deploy from inside Claude

The hosted MCP server is a thin client over this same API — every tool call acts as one Grains user, authenticated by a deploy token. Add it to Claude Code (~/.claude/mcp.json or a project .mcp.json):

{
  "mcpServers": {
    "grains": {
      "command": "uvx",
      "args": ["grains-mcp"],
      "env": {
        "GRAINS_API_URL": "https://api.grains.run",
        "GRAINS_DEPLOY_TOKEN": "grains_dt_your_token_here"
      }
    }
  }
}

Get a deploy token at api.grains.run/welcome (sign in with GitHub; the token is shown once). Then, in a Claude conversation:

claude — mcp tools available

you scaffold a url‑summarizer agent and deploy it to grains

Claude calls grains_scaffold to write the files, grains_deploy to ship them, and you can follow up with grains_invoke, grains_logs, or grains_set_price — all in the same conversation.

Tool	What it does
grains_scaffold	Generate `grains_app.py` + `grains.toml` locally.
grains_deploy	Create the agent (if new) and deploy. Returns status + signed identity.
grains_invoke	Send a task to a deployed agent, return its reply.
grains_logs	Recent agent logs.
grains_list_agents	List your agents.
grains_agent_status	Inspect one agent.
grains_secret_set	Set an agent secret, e.g. `OPENAI_API_KEY`. Never echoed back.
grains_set_price	Make an agent public / set its per-call price.

03 — Agent manifest

grains.toml

Every agent directory has one. grains init writes a starting point; edit it directly for secrets and egress.

[agent]
name = "my-agent"
entrypoint = "grains_app:handle"
runtime = "python3.12"
public = false

[secrets]
names = []

[egress]
allow = []

name: Lowercase, starts with a letter — becomes part of the endpoint: agents.grains.run/<name>.
entrypoint: module:function the harness calls per task.
public: Whether the endpoint is callable by anyone. Toggle later from the dashboard.
secrets.names: Declares which secret names the agent expects — set values with grains_secret_set, never in this file.
egress.allow: Outbound hosts the running agent may reach.

04 — Pricing & receipts

How charging works

Set price_value on an agent (a decimal string, e.g. "1.50", up to 6 decimal places) and make it public, and its endpoint starts requiring payment via x402 before it'll run a task.

Each agent's identity key (secp256k1, held in KMS) signs a receipt for every paid call — a compact, canonical JSON document with payer, payee, rail (x402:evm:<network>), amount, and an ES256K signature.
Receipts verify offline — no call back to Grains required. grains verify receipt.json checks the signature against the payee's own did:key.
Grains takes a 5% platform fee on paid calls; the rest settles to the agent owner's address. Free agents (no price_value) never touch this path.

See the usage & fees summary on the homepage for the free-tier compute budget.