# Connect Autumn to your agent

Paste this into Claude Code, Codex, Cursor, Devin or any agent that has a shell:

```text
Read https://www.autumn.ai/agent-quickstart.md with curl and follow it to connect me to Autumn.
```

Everything below is for the agent.

---

Autumn is a research agent that runs in the cloud: it takes a brief, works for a few
minutes, and returns rows with sources. Connecting it takes three steps.

Ground rules: never ask the user to paste a key into chat, and never print, log or commit
one. Ask the user only what you can't work out yourself.

## 1. Get access

Skip to step 2 if access already works: `autumn credits`, or
`curl -sS -o /dev/null -w '%{http_code}' https://api.autumn.ai/credits -H "X-API-Key: $AUTUMN_API_KEY"`
returns `200`. A key that is set but gets `401` has been revoked; sign in again.

Otherwise sign the user in. They approve in a browser on any device, including their
phone, and new users create their account on the same page.

**With npm**, if you only need MCP or the CLI:

```bash
npm install -g @autumnai/cli
autumn login --no-browser
```

It prints a link and a code. Give both to the user and wait. The CLI keeps the key in its
own config. If it exits with code 3, the approval is still pending: run `autumn login`
again to keep waiting.

**Over HTTP**, if there's no npm or the key needs to go into this project's code:

```bash
curl -sS -X POST https://api.autumn.ai/auth/device \
  -H "Content-Type: application/json" -d '{"client": "Claude Code", "host": "<machine name>", "email": "<user email, if known>"}'
```

Optionally include `email` when you know it; the sign-in page is prefilled.
Give the user `verification_uri_complete` and `user_code`. Then poll every `interval`
seconds with the `device_code`, keeping the response out of the transcript:

```bash
r=$(curl -sS -X POST https://api.autumn.ai/auth/device/token \
  -H "Content-Type: application/json" -d '{"device_code": "<device_code>"}')
printf '%s' "$r" | grep -oE '"(status|error)": *"[^"]*"'
case "$r" in *'"approved"'*)
  export AUTUMN_API_KEY=$(printf '%s' "$r" | sed -n 's/.*"api_key": *"\([^"]*\)".*/\1/p')
  (umask 077; printf '\nAUTUMN_API_KEY=%s\n' "$AUTUMN_API_KEY" >> .env) ;;
esac
```

- `pending`: keep polling.
- `approved`: the same command has exported `AUTUMN_API_KEY` and appended it to `.env`
  without printing it. The key is shown only once, so keep it in one command. Make sure
  `.env` is git-ignored, or use the user's secret store if the project has one.
- `error` instead: `slow_down` means poll less often, `access_denied` means the user
  declined, and `expired_token` means the code is older than 10 minutes, so start again.

**No human around?** An agent with its own AgentMail identity can sign up by itself at
https://platform.autumn.ai/sign-up with **Continue with AgentID**, then open the link from
either flow above in the same browser and approve it.

## 2. Choose how to use it

Pick from what the user asked for and what's in the working directory. If it's still
unclear, ask one question: "Should I add Autumn as tools here (MCP), use it from the
terminal (CLI), or build it into this project's code?"

- **MCP tools in this agent.** No key involved; the user signs in through the browser.
  - Claude Code: `claude mcp add --transport http autumn https://api.autumn.ai/mcp`,
    then `/mcp` and **Authenticate**.
  - Claude.ai or ChatGPT: the user adds `https://api.autumn.ai/mcp` as a custom connector
    in the app.
  - Other clients: https://www.autumn.ai/docs/mcp
- **CLI.** If `autumn` isn't installed yet, run `npm install -g @autumnai/cli`.
  `autumn run "<brief>" --out rows.csv` starts a task and saves its rows.
- **Project code.** Read `AUTUMN_API_KEY` from the environment on the server, never in a
  browser bundle. The request loop is in the Skill; the full contract is
  https://api.autumn.ai/openapi.json

## 3. Check and hand off

1. Check access with `autumn credits` or
   `curl -sS https://api.autumn.ai/credits -H "X-API-Key: $AUTUMN_API_KEY"`. It's free.
   Tell the user their balance.
2. Install the Skill so later sessions know how to brief Autumn:
   `npx skills add https://www.autumn.ai`, `autumn setup`, or without npm download
   https://www.autumn.ai/skill.md as `autumn/SKILL.md` in your agent's skills folder.
3. Read https://www.autumn.ai/skill.md and do what the user asked for.