Skip to docs content
Browse documentation
On this page

First steps

Minion exposes search and execute as the two MCP tools. The agent should search first to find the right capability, official guide, package, note, or team skill, then run work through execute. Official guides open with search({ entities: ["guide:{id}"] }), not execute.

Habits that help

  • Reuse the returned conversation id. If a search response included a conversationId, pass it back unchanged on follow-up searches so they stay compact. Otherwise omit the field and use the server-generated value. Do not make one up locally.
  • Start broad. An empty search({}) returns the domain index. Open a domain with search({ domain: "jobs" }), or rank inside it with search({ query, domain }).
  • Let memories surface. Minion adds the one or two most relevant memories to a search with a query, and to an execute call based on its code and params. There is nothing to pass for that. See Shared memory .
  • Read quota errors. A plan-limit denial keeps its error text, which names the plan and the limit. minion.account.usage() shows where you stand against each daily limit.
  • Think in packages for reusable saved code. Packages expose exports, declare package-owned jobs, and can optionally serve an app. Recurring schedules belong on a package in the jobs list of its minion block. Deferred one-shot work uses minion.workflows.create({ runAt }). minion.jobs.runNow fires an existing job immediately for debugging or catch-up runs, and minion.jobs.update changes a job's schedule or enabled state without rewriting package source.
  • Check your team's packages before creating one. Packages are shared inside your team, so search and minion.packages.list() show what already exists. Sharing with other teams isn't available yet. See Sharing packages .
  • Bootstrap integration-backed work before building. When a package, package app, or workflow depends on OAuth, a saved secret, or a third-party API, confirm the integration or secret exists, run a cheap authenticated smoke test in execute, then build the downstream artifact. See Integration bootstrap .
  • Ask for natural-language goals, for example: “Search Minion for a way to run something every morning” or “Find a saved package for Cloudflare DNS helpers.”
  • Credentials use the dashboard. Never paste a secret into chat. An owner or admin adds secrets at /app/secrets and connects OAuth logins at /app/integrations, as described in Secrets and host approval . Per-provider walkthroughs live at minion.codes/docs/connect (each page also serves raw markdown at /docs/<slug>.md).
  • Confirm destructive work before mutating GitHub, Cloudflare, or other remote systems. See Mutating actions and confirmations .
  • Verify before changing memory. If you think something should become durable memory, call minion.memories.verify first, review related memories, and only then choose minion.memories.upsert or minion.memories.delete.
  • Check what is waiting on a person. minion.waiting.list() returns the approvals and reconnects that only a person can clear, each with a link to send them.

Where to go next