# Use it from your agent

> Connect Claude Code, Cursor, Codex or any agent over MCP or HTTP to set up RedNest, start scans, read findings and fix them.

Anything you can do in the dashboard, your agent can do for you: connect, install guidance, start deep scans, read findings and change settings. You only step in where a person has to: approving the agent once and installing the GitHub App when needed.

Hosted access uses **one lifetime free scan** per GitHub account. **$RED holder scanning is not active yet.** Do not assume payment, credit packs or holder eligibility are available. See [Pricing & $RED access](https://rednest.tech/docs/pricing).

## The quickest way

Press **Set up with your agent** on the home page and paste the prompt into your agent. It reads this page and does the rest:

```text
Set up RedNest for me: it finds exploitable vulnerabilities in my GitHub repositories (https://rednest.tech).
Read https://rednest.tech/docs/agents.md and follow it. Connect to its MCP server (https://rednest.tech/api/mcp) if you can add one, otherwise use its HTTP API with the device flow.
Then call get_me and work through next_steps. Only ask me for what needs me: approving the connection and installing the GitHub App. Do not assume payment or free credits are available.
```

## For agents: how to set RedNest up

1. **Connect.** Add the MCP server if your harness supports remote MCP ([below](#connect-over-mcp)); the person approves in their browser. Otherwise use the [device flow](#connect-over-http) over HTTP and keep the API key (`SANDCHEST_API_KEY`).
2. **Call `get_me`** (`GET /api/v1/me`). Work through `next_steps` in order.
3. **No accounts?** The person must install the GitHub App: give them `links.install_github_app`. Then call `list_accounts` with `wait=50`.
4. **Scan.** Prefer `start_deep_scan` when the account is ready. The first chargeable scan for that GitHub user may use the lifetime free entitlement. Do not assume Stripe checkout or credit packs are required for that free scan.
5. **Fix.** In a checkout, `get_findings_prompt` (or `get_fix_prompt`) gives fix prompts. When the fix reaches the default branch, RedNest re-checks open findings.

Wallet verification for planned $RED holder access is done in the browser under [Settings](https://rednest.tech/dashboard/settings#wallet), not through a token transfer API.

## Connect over MCP

The MCP server is `https://rednest.tech/api/mcp` (Streamable HTTP).

```bash
# Claude Code
claude mcp add --transport http sandchest https://rednest.tech/api/mcp

# Codex
codex mcp add sandchest --url https://rednest.tech/api/mcp
codex mcp login sandchest
```

```json
{
  "mcpServers": {
    "sandchest": { "url": "https://rednest.tech/api/mcp" }
  }
}
```

(The MCP server id may still appear as `sandchest` in client configs.) A client that can't do OAuth can send an [API key](#api-keys) as `Authorization: Bearer <key>`.

## Connect over HTTP

```bash
curl -s -X POST https://rednest.tech/api/v1/auth/device \
  -H 'content-type: application/json' -d '{"client_name":"My agent"}'
```

Give the person `verification_uri_complete`, then:

```bash
curl -s -X POST https://rednest.tech/api/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d device_code=scd_… -d wait=50
```

Then call the API with the returned key:

```bash
curl -s https://rednest.tech/api/v1/me -H "Authorization: Bearer $SANDCHEST_API_KEY"
```

## API keys

API keys act as the person who made them. Create or revoke them in **Settings → Agents**. If GitHub sign-in expires, calls may answer `403 github_reauth_required` until they sign in again at [sign-in](https://rednest.tech/sign-in).

## Tools and endpoints

Every tool is also an HTTP endpoint under `https://rednest.tech/api/v1`. `GET /api/v1` lists them; [`/api/v1/openapi.json`](https://rednest.tech/api/v1/openapi.json) describes them.

| Tool | Endpoint | What it does |
| --- | --- | --- |
| `get_me` | `GET /me` | Who you act as, accounts, and `next_steps` |
| `list_api_keys` | `GET /keys` | API keys and connected MCP clients |
| `create_api_key` | `POST /keys` | A new API key, shown once |
| `revoke_api_key` | `DELETE /keys/{id}` | Revoke a key or disconnect a client |
| `list_accounts` | `GET /accounts` | Installed GitHub accounts; `wait` while installing |
| `get_account` | `GET /accounts/{account}` | Settings, hacker and repositories |
| `update_account` | `PATCH /accounts/{account}` | Check threshold, emails, company details |
| `update_hacker` | `PATCH /accounts/{account}/hacker` | Hacker profile |
| `list_repos` | `GET /repos` | Repositories and open findings |
| `get_repo` | `GET /repos/{repo}` | One repository, recent scans and threat model |
| `start_deep_scan` | `POST /repos/{repo}/scans` | Deep scan a whole repository |
| `list_scans` | `GET /scans` | Scans, newest first |
| `get_scan` | `GET /scans/{id}` | A scan and its findings; optional `wait` |
| `get_scan_events` | `GET /scans/{id}/events` | Live feed |
| `list_findings` | `GET /findings` | Findings by status, severity and repository |
| `get_finding` | `GET /findings/{id}` | Attack path, PoC, fix guidance |
| `get_fix_prompt` | `GET /findings/{id}/fix-prompt` | Fix prompt for one finding |
| `get_findings_prompt` | `GET /findings/prompt` | Prompt for many findings |
| `update_finding` | `PATCH /findings/{id}` | Dismiss, mark fixed, or reopen |
| `get_overview` | `GET /overview` | Reviews, scans, findings and fixes over time |

Legacy billing tools (`get_billing`, `quote_credits`, `buy_credits`, `claim_free_credits`, and related) may still appear in the OpenAPI surface for accounts that use the older credits module. They are **not** the public $RED access model. Prefer free-scan / future holder entitlements described in [Pricing](https://rednest.tech/docs/pricing).

## Errors

Errors come back as `{"error": {"code": "…", "message": "…"}}`. Codes to act on:

| Status | Code | What to do |
| --- | --- | --- |
| 401 | `unauthorized`, `invalid_token` | Connect again. |
| 403 | `github_reauth_required` | Person signs in at `sign_in_url`. |
| 403 | `not_admin` | Only an account admin can do this. |
| 404 | `not_found`, `repo_not_found`, `account_not_found` | List accounts/repos to find the id. |
| 409 | `already_running` | Follow the running scan (`scan_id`). |
| 422 | `invalid_input` | See `issues` for fields. |

If a scan is refused for entitlement reasons, tell the person to check [Pricing](https://rednest.tech/docs/pricing) and [Settings](https://rednest.tech/dashboard/settings) (free scan used, wallet not verified, or holder scanning not active yet).