# AgentDrive · SDKs & developer kit

> How to build against AgentDrive. The **fastest path is the plugin or
> the MCP connector** — both handle OAuth, no API key to paste. Language
> SDKs and the raw REST conventions are below, in that order of
> recommendation. The endpoint + schema reference is **generated** and
> authoritative at `https://api.agentdrive.run/openapi.json`.

Repo: <https://github.com/Mnexa-AI/agentdrive-sdk> (SDKs + skill +
connector). API base: `https://api.agentdrive.run`.

## Fastest path

### Plugin (recommended)

One command wires the AgentDrive MCP server, installs the `agentdrive`
skill, and adds the `/publish` `/drive` `/compile` commands:

```
npx plugins add Mnexa-AI/agentdrive-sdk
```

Per-agent install:

- **Claude Code** — `claude plugin marketplace add Mnexa-AI/agentdrive-sdk`, then `claude plugin install agentdrive@agentdrive`
- **Codex** — `codex plugin marketplace add Mnexa-AI/agentdrive-sdk`, then `codex plugin add agentdrive@agentdrive`
- **Cursor** — `/add-plugin agentdrive`

First tool use opens the OAuth sign-in in your browser — no API key to
paste.

### MCP connect (no plugin)

Add the MCP endpoint directly (Streamable HTTP, OAuth 2.1):

```
https://api.agentdrive.run/mcp
```

- **ChatGPT** — Settings → Apps → Advanced settings → Developer mode; create a custom MCP app and enter `https://api.agentdrive.run/mcp` (availability depends on plan and workspace permissions)
- **Claude web / Desktop / Cowork / mobile** — Customize → Connectors → + → Add custom connector; enter `https://api.agentdrive.run/mcp`
- **Claude Code** — `claude mcp add --transport http agentdrive https://api.agentdrive.run/mcp`
- **Codex CLI / Desktop** — `codex mcp add agentdrive --url https://api.agentdrive.run/mcp`, then `codex mcp login agentdrive`
- **Cursor** — Settings → Tools & MCP → Add custom MCP; enter `https://api.agentdrive.run/mcp`
- **Gemini CLI** — add a remote HTTP server named `agentdrive` with URL `https://api.agentdrive.run/mcp` in `settings.json`
- **Any other OAuth-capable MCP client** — add `https://api.agentdrive.run/mcp` as a remote Streamable HTTP server; the client must support OAuth

See https://agentdrive.run/setup.md for the human OAuth walkthrough and https://agentdrive.run/auth.md for
autonomous agent self-registration.

## Language SDKs

Generated clients for the REST API, produced from `https://api.agentdrive.run/openapi.json` via
openapi-generator:

- **Python** — `pip install agentdrive-sdk` *(once published — not yet on
  PyPI)*
- **TypeScript / Node** — `npm install @agentdrive/sdk` *(once published —
  not yet on npm)*
- **Go** — `go get github.com/Mnexa-AI/agentdrive-sdk/sdk/go` *(available
  now)*

**Caveat:** the bare `agentdrive` package on PyPI is a *parked
placeholder* (a print-and-exit stub — the stdio MCP companion it once
held has been retired), **not** the REST SDK. The REST SDK is
`agentdrive-sdk`.

To regenerate or self-host a client, point openapi-generator at
`https://api.agentdrive.run/openapi.json`.

## Raw REST (lower-level fallback)

If you're not using MCP or a generated SDK, talk to the REST API
directly. The cross-cutting conventions are below; the **endpoint +
schema reference is generated** and authoritative at `https://api.agentdrive.run/openapi.json`.

Base URL: `https://api.agentdrive.run/v0`

### Authenticating

Every `/v0/*` request takes `Authorization: Bearer <credential>`. Two
credentials work on REST:

- **API key** — `Bearer ad_live_…`, minted by a human from the dashboard
  (Settings → API keys / Quickstart). Long-lived; good for scripts and CI.
- **Access token** — `Bearer <access_token>`, the 15-minute token you get
  from `https://api.agentdrive.run/oauth2/token`. See https://agentdrive.run/auth.md (agent self-registration) or
  https://agentdrive.run/setup.md (human OAuth) for how to obtain one.

The MCP OAuth tokens (`adat_…`) are **MCP-only** and are rejected on
`/v0` — use an API key or an access_token for REST.

### Error shape

Errors are a structured envelope with a machine code and a human message:

```json
{
  "detail": {
    "error": { "code": "BAD_CURSOR", "message": "…human-readable…" }
  }
}
```

Branch on `detail.error.code` (e.g. `INVALID_PATH`, `NOT_FOUND`,
`ARTIFACT_TOO_LARGE`), not on the prose. The HTTP status carries the
class (4xx client, 5xx server); the code carries the specifics.

### Pagination

List endpoints are cursor-paginated. A page response carries `items` plus
`next_cursor`. When there's more, `next_cursor` is a token — pass it back
as `?cursor=<token>` for the next page. On the final page `next_cursor` is
`null`. Cursors are opaque; don't construct or mutate them (a malformed
cursor returns `BAD_CURSOR`).

### Rate limits

Every authenticated response is stamped with the current budget:

```
X-RateLimit-Limit:     <ceiling for this window>
X-RateLimit-Remaining: <calls left>
X-RateLimit-Reset:     <epoch seconds when the window resets>
```

On a 429 the response adds `Retry-After: <seconds>` and the structured
error body. Back off until the reset rather than retrying immediately.

Full endpoint + request/response schema reference: `https://api.agentdrive.run/openapi.json`.