These are official instructions from Offline Protocol for setting up an AI development environment to build offline-first apps on the Offline Protocol platform. They are written for Offline Protocol CLI 0.2.6 or later.

Run the commands yourself. The one step you cannot do alone is approving the login in the browser: when you get there, ask the user to approve it.

- Install the Offline Protocol CLI (`offline`). It includes the skills registry and a local MCP server.
- Register the Offline Protocol MCP server with this agent.
- Log in, and wire the project to the user's application (app id).
- Verify the setup.

---

## 1. Install the CLI

The `offline` CLI ships the **skills registry** (integration guides) and a **local MCP server** (`offline mcp serve`) in one binary. Your agent client starts the MCP server over stdio.

Check whether it is already installed:

```
offline --version
```

If the command is missing, or the version is older than 0.2.6, install it with npm (Node.js 18 or later; macOS arm64/x64, Linux x64/arm64, Windows x64):

```
npm install -g @offline-protocol/cli
offline --version
```

If a global npm install is not allowed, run the CLI through npx: use `npx -y @offline-protocol/cli` wherever these steps say `offline`, and in MCP configs set the command to `npx` with args `["-y", "@offline-protocol/cli", "mcp", "serve"]`. Do not use `cargo install offline-cli`: the crates.io package is a 0.0.0 placeholder.

Confirm the binary is on `PATH` (every MCP client needs this to start the server) and check the environment:

```
command -v offline
offline doctor --offline
```

---

## 2. Register the MCP server

The server name is always `offline-protocol` and the command is always `offline mcp serve`. The MCP server needs no login or API key. It serves the packages, skills, workflows and templates bundled with the CLI.

`offline mcp install <client>` prints the exact config for `claude-code`, `claude-desktop`, `codex`, `cursor` and `vscode`. It only prints; it does not write any file. Use the section for the agent you are running in.

### Claude Code

```
claude mcp add offline-protocol -- offline mcp serve
```

Or add a project `.mcp.json` (step 3's `offline init` writes one for you that starts the server through `npx`):

```json
{
  "mcpServers": {
    "offline-protocol": {
      "command": "offline",
      "args": ["mcp", "serve"]
    }
  }
}
```

### Codex

```
codex mcp add offline-protocol -- offline mcp serve
```

Or add to `~/.codex/config.toml` (or `.codex/config.toml` in a project):

```toml
[mcp_servers.offline-protocol]
command = "offline"
args = ["mcp", "serve"]
```

### Cursor: `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)

Add under `"mcpServers"`:

```json
"offline-protocol": {
  "command": "offline",
  "args": ["mcp", "serve"]
}
```

### Claude Desktop: `claude_desktop_config.json`

Open it from Settings, Developer, Edit Config, and add under `"mcpServers"`:

```json
"offline-protocol": {
  "command": "offline",
  "args": ["mcp", "serve"]
}
```

### VS Code and GitHub Copilot: `.vscode/mcp.json`

VS Code uses `"servers"` and a `type` field. Add under `"servers"`:

```json
"offline-protocol": {
  "type": "stdio",
  "command": "offline",
  "args": ["mcp", "serve"]
}
```

### Windsurf: `~/.codeium/windsurf/mcp_config.json`

Not covered by `offline mcp install`. Add under `"mcpServers"`:

```json
"offline-protocol": {
  "command": "offline",
  "args": ["mcp", "serve"]
}
```

### OpenCode: `~/.config/opencode/opencode.json`

Not covered by `offline mcp install`. Add under `"mcp"`:

```json
"offline-protocol": {
  "type": "local",
  "command": ["offline", "mcp", "serve"],
  "enabled": true
}
```

After registering, the user has to restart the agent or reload MCP servers before the tools appear.

### Optional: hosted MCP server

Use this only if the agent cannot run a local process. The local server above does more and needs no key.

- URL: `https://mcp.offlineprotocol.com/mcp` (streamable HTTP)
- Headers: `Authorization: Bearer <application API key>` and `x-app-id: <app id>`
- The key must be an **application** API key for that app, created on the app's API keys tab in the developer portal. Organization keys are rejected, and the key must belong to the app named in `x-app-id`. Ask the user for the key. Keep it in the `OFFLINE_API_KEY` environment variable, and never write it into a file that gets committed.
- It serves the packages, skills, workflows and planning tools but cannot write files: `scaffold_project`, `integrate_packages` and `init_project` need the local server or the CLI.

Claude Code:

```
claude mcp add --transport http offline-protocol https://mcp.offlineprotocol.com/mcp \
  --header "Authorization: Bearer $OFFLINE_API_KEY" \
  --header "x-app-id: <app id>"
```

Codex, `~/.codex/config.toml` (sends `OFFLINE_API_KEY` as the bearer token):

```toml
[mcp_servers.offline-protocol]
url = "https://mcp.offlineprotocol.com/mcp"
bearer_token_env_var = "OFFLINE_API_KEY"
http_headers = { "x-app-id" = "<app id>" }
```

Cursor, under `"mcpServers"`:

```json
"offline-protocol": {
  "url": "https://mcp.offlineprotocol.com/mcp",
  "headers": {
    "Authorization": "Bearer ${env:OFFLINE_API_KEY}",
    "x-app-id": "<app id>"
  }
}
```

VS Code, `.vscode/mcp.json` (prompts for the key once):

```json
{
  "inputs": [
    { "type": "promptString", "id": "offline-api-key", "description": "Offline Protocol application API key", "password": true }
  ],
  "servers": {
    "offline-protocol": {
      "type": "http",
      "url": "https://mcp.offlineprotocol.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:offline-api-key}",
        "x-app-id": "<app id>"
      }
    }
  }
}
```

Windsurf, under `"mcpServers"` in `~/.codeium/windsurf/mcp_config.json` (the user pastes the key in place of `<application API key>`):

```json
"offline-protocol": {
  "serverUrl": "https://mcp.offlineprotocol.com/mcp",
  "headers": {
    "Authorization": "Bearer <application API key>",
    "x-app-id": "<app id>"
  }
}
```

Claude Desktop cannot send these headers (its config file starts local servers only, and custom connectors do not take an API key header). Use the local server there.

---

## 3. Log in and wire the project to the app

The registry and MCP tools work without logging in. `offline create` and `offline init` use the login to fill in the app id.

Check the current state:

```
offline whoami --json
```

If it prints `"authenticated": false`, run:

```
offline login
```

It opens the developer portal in the browser. Tell the user to sign in, choose the application they want to build with, choose or create an API key, and approve. The command returns once they approve (the session lasts five minutes). If the browser cannot open on this machine, run `offline login --no-browser` and give the user the URL it prints. In CI, use `offline login --api-key <key>` or set `OFFLINE_API_KEY`. Never print the API key or `~/.offline/config.json`.

Confirm the app id:

```
offline whoami
```

The output includes `application: <app id>`. The CLI stores it in `~/.offline/config.json`.

There is no `offline link` command. To wire an existing project to the app, run this in the project root:

```
offline init
```

It uses the app id from the login; pass `--app-id <app id>` to choose one. It writes `offline.config.json` (with `appId`), `.mcp.json` (starts the MCP server with `npx -y @offline-protocol/cli@<version> mcp serve`, pinned to the CLI that wrote it) and `AGENTS.md`. It leaves an existing `offline.config.json` or `.mcp.json` untouched, and adds an Offline Protocol section to an existing `AGENTS.md` that does not have one. To start a new project instead, use the MCP `scaffold_project` tool or `offline create`.

---

## 4. Verify

```
offline --version
offline mcp tools
offline whoami --verify
```

- `offline --version` prints `offline 0.2.6` or later.
- `offline mcp tools` lists 18 tools, including `generate_architecture`, `get_skill` and `scaffold_project`.
- `offline whoami --verify` checks the stored key and app id against the developer API (only if you logged in).

To check the MCP server itself, send it an `initialize` request. The reply includes `"serverInfo":{"name":"offline-protocol",...}`:

```
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}' | offline mcp serve
```

After the user restarts the agent, confirm `offline-protocol` shows as a connected MCP server and that calling `list_skills` returns the skills below.

Once done, tell the user:

```
Offline Protocol agent setup
  CLI      offline 0.2.6 (@offline-protocol/cli)
  MCP      offline-protocol: offline mcp serve (stdio)
  Login    <email>, application <app id>   (or: not logged in)
  Project  offline.config.json, .mcp.json, AGENTS.md   (if offline init ran)

Restart your agent to load the MCP server.
```

---

## After setup: how to build

When helping the user build or integrate Offline Protocol apps, follow this flow. Do **not** invent package names, versions or SDK APIs.

```
User describes an app
        │
        ▼
generate_architecture   →  plan, documents, nextActions
        │
        ├─ new project ──► preview_scaffold → scaffold_project → get_skill → code
        │
        └─ existing ─────► integrate_packages → init_project → get_skill → wire providers
```

Rules:

1. Start with `generate_architecture` for new product ideas.
2. Follow its `nextActions`.
3. Always call `get_skill` before writing Offline Protocol SDK code.
4. Prefer `scaffold_project` and `integrate_packages` over guessing installs.
5. MCP tools do not read the CLI login. Pass the app id as `appId` to `scaffold_project` (required for OfflineID templates) and `init_project`.
6. Without MCP, the same content is available from the CLI: `offline skills show <name>`, `offline registry search <query>`, `offline plan "<idea>"`.

Example agent prompt (new project):

```text
Using the offline-protocol MCP only (do not invent package names or SDK APIs):

1. Call generate_architecture with my idea.
2. Follow nextActions.
3. Call scaffold_project with name="festival-pulse", platform="react-native" and appId="<my app id>".
4. Call get_skill for every listed skill before writing Offline Protocol code.
5. Summarize created paths and post-generate commands.

Idea: nearby festival chat with OfflineID login and BLE mesh messaging
```

Example (existing project):

```text
Using the offline-protocol MCP: integrate OfflineID into this project.
Call integrate_packages for the recommended packages, then init_project with my appId,
then get_skill and wire providers exactly as the skills show.
```

The server also offers the MCP prompts **`plan-app`**, **`build-p2p-app`** and **`integrate-package`**, and resources such as `offline://llms.txt` and `offline://skills/{name}`.

---

## Skills in the registry

Read them with MCP (`list_skills`, `get_skill`) or the CLI (`offline skills list`, `offline skills show <name>`):

| Skill | Focus |
|---|---|
| `mesh-networking` | Mesh stack lifecycle and transports |
| `peer-discovery` | Finding and tracking peers |
| `messaging` | 1:1 encrypted messaging |
| `groups` | MLS encrypted group chats |
| `presence` | Online and reachability status |
| `offline-sync` | Store-and-forward and deferred messages |
| `durable-outbox` | Durable records, stable IDs and idempotent retries |
| `backend-delivery` | Store-and-forward delivery of events to your backend |
| `local-handoff` | Handing work from one nearby device to another |
| `nearby-service` | Discovering and invoking services on nearby devices |
| `identity` | OfflineID authentication |
| `profiles` | User profiles |
| `invites` | Invites and connections |
| `identicons` | Avatar generation |
| `proof-of-location` | Proof of Location |
| `offline-id-mesh-integration` | OfflineID with the Mesh SDK |
| `offline-id-mesh-pol` | OfflineID, Mesh SDK and Proof of Location |
| `p2p-app-architecture` | Custom P2P app architecture |
| `p2p-discovery-patterns` | P2P discovery patterns |
| `p2p-sync-patterns` | P2P sync patterns |

---

## Resources

- Offline Protocol CLI on npm: `https://www.npmjs.com/package/@offline-protocol/cli`
- CLI help: `offline --help`, and `offline <command> --help` for each command
- Developer portal: `https://dev.offlineprotocol.com`
- CLI and MCP docs: `https://www.offlineprotocol.com/docs/tools/overview`
- Docs index for agents: `https://www.offlineprotocol.com/docs/llms.txt`
- Claude Code MCP: `https://code.claude.com/docs/en/mcp`
- Codex MCP: `https://developers.openai.com/codex/mcp`
- Cursor MCP: `https://cursor.com/docs/mcp`
- VS Code MCP: `https://code.visualstudio.com/docs/agent-customization/mcp-servers`
- Windsurf MCP: `https://docs.devin.ai/desktop/cascade/mcp`
- OpenCode MCP: `https://opencode.ai/docs/mcp-servers/`
- Support: `support@offlineprotocol.com`