# devin-api-mcp

A single **`devin-api`** MCP server providing **full Devin API coverage** — manage sessions, knowledge, playbooks, secrets, schedules, and attachments programmatically from any MCP client — plus the read-only **DeepWiki** documentation tools (`ask_question`, `read_wiki_structure`, `read_wiki_contents`).

Unlike the hosted [Devin MCP](https://docs.devin.ai/work-with-devin/devin-mcp), which routes all operational tools through the v3 API (rejecting personal `apk_` keys, so sessions can't be attributed to the dispatching user), this server backs the core tools with the **v1 API and your personal key** — sessions show up in *your* Devin dashboard.

## The workflow

The intended shape: a local agent (Claude Code, Codex, …) does the thinking on your machine — planning, design, review — consulting DeepWiki as an on-demand codebase expert, then delegates well-scoped implementation tasks to Devin cloud sessions and gathers the results.

```mermaid
flowchart LR
    subgraph local["🖥️ Your machine"]
        agent["Claude Code / Codex<br/><i>planning · design · review</i>"]
    end
    subgraph cloud["☁️ Devin cloud"]
        wiki["DeepWiki<br/><i>codebase expert</i>"]
        d1["Devin session"]
        d2["Devin session"]
    end
    agent <-- "ask_question<br/>read_wiki_*" --> wiki
    agent -- "create_session<br/>send_message" --> d1
    agent -- "delegate scoped tasks" --> d2
    d1 -- "gather_sessions → PRs, results" --> agent
```

## Quickstart

**Claude Code:**

```bash
claude mcp add -s user -e DEVIN_PERSONAL_API_KEY=<your-personal-key> -- devin-api npx -y -p @jsklan/devin-api-mcp devin-api
```

**Codex:**

```bash
codex mcp add devin-api --env DEVIN_PERSONAL_API_KEY=<your-personal-key> -- npx -y -p @jsklan/devin-api-mcp devin-api
```

**Gemini CLI:**

```bash
gemini mcp add -e DEVIN_PERSONAL_API_KEY=<your-personal-key> devin-api npx -y -p @jsklan/devin-api-mcp devin-api
```

Get your personal key (`apk_user_` prefix) from [app.devin.ai](https://app.devin.ai) → Settings → API Keys. Optionally add a second `DEVIN_SERVICE_API_KEY=<org-service-key>` env var (`cog_` prefix, from org settings) to also enable the v3 organization tools (schedules, insights, archive, message history).

## The server documents itself

Full setup, credential, and configuration docs are **built into the server** — no need to keep this README open:

- Installed with **no keys at all**, the server starts in **setup mode**: it exposes a single `get_setup_docs` tool and instructs the connected agent to walk you through obtaining and configuring credentials. So the zero-knowledge onboarding path is just: install, connect, ask your agent to set it up.
- With keys configured, `get_setup_docs` remains available for reference (adding the second key, migrating configs, other MCP clients, plugin install).

To install as a **Claude Code plugin** instead: `/plugin` → Marketplaces → add `jsklan/devin-api-mcp` → install **devin-api** (keys via environment variables, same as above).

## What you get

Which tools are registered depends on which keys are set; tools whose backing key is absent are simply not registered — nothing shows up broken.

- **Personal key** (`DEVIN_PERSONAL_API_KEY`, `apk_user_`; `DEVIN_API_KEY` accepted as fallback) — sessions (create/list/get/message/gather/terminate/tag), knowledge, playbooks, secrets, attachment upload, **plus the three DeepWiki docs tools** (proxied to `mcp.devin.ai` with your key, so private repos work).
- **Service key** (`DEVIN_SERVICE_API_KEY`, `cog_`) — the v3-exclusive organization tools: schedules, session insights, archive/delete, paginated message history, tag management, attachment download.
- **Attribution rule:** with both keys, capabilities that exist in both APIs stay backed by v1 + your personal key so sessions remain user-attributed; the service key only adds its exclusives.

Run `get_setup_docs` (or read [`src/setup-docs.ts`](src/setup-docs.ts)) for the full breakdown.

## Deprecated aliases

- **`deepwiki`** (standalone docs-only proxy server) — merged into `devin-api` in 1.1.0. The bin still works but prints a deprecation warning; remove the separate `deepwiki` entry from your MCP config.
- **`devin-api-v1` / `devin-api-v3`** — unified into `devin-api` in 1.0.0; both aliases launch the unified server.

Tool names are unchanged in both migrations, so existing prompts and automations keep working. Aliases will be removed in a future major version.

## API Coverage

- The v1 tool set wraps the [Devin REST API v1](https://docs.devin.ai/api-reference/v1/overview.md).
- The v3 tool set wraps the Devin REST API v3 organization endpoints (`org_id` auto-discovered at startup via `/v3/self`). Enterprise (`/v3/enterprise/...`) and beta (`/v3beta1/...`) endpoints are intentionally excluded.
- The DeepWiki tools proxy to the upstream Devin MCP server (`DEEPWIKI_UPSTREAM_URL`, default `https://mcp.devin.ai/mcp`; optional `DEVIN_ORG_ID` header).

Written in TypeScript with Zod schema validation.

## License

MIT