# AI connector (MCP)

The connector speaks the Model Context Protocol and signs you in with OAuth. You choose one workspace or all of them, and read-only or read-and-manage access. It then does what your role allows — nothing more — through the same API, with the same limits, audit rows and money checks. Its tools cover projects and deploys, repos, environment variables, databases, storage, functions, vector collections, memory, agents, domains and DNS, payments, sign-in, mail, usage and these docs.

It is tested with Claude. ChatGPT and other MCP clients speak the same protocol and the steps below connect them, but they are not verified yet.

## Connect

| Client | How |
| --- | --- |
| Claude (web and desktop) | Settings → Connectors → Add custom connector → paste `https://harakumo.com/mcp` → sign in and choose the workspace and access. |
| Claude Code | `claude mcp add --transport http harakumo https://harakumo.com/mcp` |
| ChatGPT | Turn on developer mode, add an app with the URL `https://harakumo.com/mcp` and OAuth sign-in. Step by step in Connect ChatGPT below. |
| Other clients (Cursor …) | `{ "mcpServers": { "harakumo": { "url": "https://harakumo.com/mcp" } } }` |
| A headless agent | Send an API key instead: `Authorization: Bearer hk_live_…` (developer-role tools; a read-only key gets read tools). |

## Connect ChatGPT

ChatGPT's search and deep research use two read-only tools, `search` and `fetch`. `search` looks through these docs and your workspace — projects, deployments, databases, functions, storage buckets and domains — and returns results with ids like `project:12`, `deployment:340`, `domain:example.com` or `doc:deployments`. `fetch` reads one in full: a deployment comes with its build log, a docs topic as markdown. Both see only what your role and the connection allow, like every other read tool.

1. In ChatGPT on the web, open Settings and turn on Developer mode. It is available on Plus, Pro, Business, Enterprise and Education plans; ChatGPT moves the switch between releases (it has lived under Apps & Connectors and under Security).
2. Add an app (a connector): name it Harakumo, set the server URL to `https://harakumo.com/mcp` and choose OAuth for authentication.
3. Sign in to Harakumo when ChatGPT asks, then choose the workspace and Read only or Read and manage.
4. In a chat, pick Developer mode from the + menu and switch Harakumo on. Name it in your request, e.g. "Use Harakumo to show my failed deploys".

> Tools that change something ask ChatGPT to confirm first. For a ChatGPT that can only look, pick Read only on the Harakumo sign-in screen.

## Access

- Read only: the assistant can look but not change anything. Read and manage: changes are allowed; tools that change or delete things are marked so the assistant asks you first.
- A connector acts with your own role, so an admin's connector also gets admin tools such as API keys, members and the audit log; an API key gets developer tools only. Money never leaves through a connector: withdrawals, refunds and payout setup are refused by design.
- A connection stays signed in and renews itself (the access token lasts 90 days and refreshes; unused for 180 days, it expires). Dashboard → Connectors lists every connection and cuts any of them off immediately.

## Sending email from your own domain

Six tools let an assistant set up a sending domain end to end: it adds the domain, gives you the two nameservers and the steps for your provider (its existing records are copied first), checks until the switch is seen, and sets the project's From address once the domain is verified. See Mail → Send from your own domain.

- `add_mail_domain` — start (or start again); returns the nameservers, numbered steps, provider hints and the copied records.
- `check_mail_domain` — check now: whether the nameservers switched, then each record found, missing or wrong.
- `list_mail_domains` and `get_mail_domain` — status, steps and every project's current From address.
- `set_mail_from` — a project's From address and Reply-To.
- `remove_mail_domain` — stop sending from a domain.
- Also: `host_domain_dns` hosts a bought domain's DNS here so every record is added for you, and `send_email` takes `from` and `replyTo`.

## New tools not showing?

Assistants remember a connector's tool list from when it was attached. After Harakumo adds tools, disconnect and reconnect the connector, then start a new conversation. The docs themselves are always live through get_docs.

## Try asking

- "What needs my attention?" — one call to needs_attention, most urgent first.
- "Build a landing page for my bakery and put it online."
- "Why did the last deploy fail?"
- "How much of my plan and AI credit is left?"
- "Buy fruitshop.com and connect it to the store project."
- "Set up fruitshop.com as a sending domain on Harakumo and walk me through it."

## Reference

**SDK**

```js
// Nothing to install — the connector is the interface.
```

**CLI**

```bash
claude mcp add --transport http harakumo https://harakumo.com/mcp
```

**REST**

```http
POST   /mcp                                        Authorization: Bearer hk_mcp_… or hk_live_…
GET    /.well-known/oauth-protected-resource/mcp   # discovery
GET    /api/mcp/connections                        # what is connected
DELETE /api/mcp/connections                        { "id": 1 }   # disconnect
```