Offline Protocol CLI and MCP server

The Offline Protocol CLI (@offline-protocol/cli 0.2.6) installs the offline command and a local MCP server. Use them to find packages, read integration guidance, plan an application and scaffold project files. Hosted MCP provides the same registry and planning context without a local installation, but cannot write files. Neither MCP mode runs the mesh or communicates with peers. Build and test device communication with the Mesh SDK. This page covers the Offline Protocol MCP server; the separate docs MCP server at https://www.offlineprotocol.com/docs/mcp only searches and reads these documentation pages.

Install

Requires Node.js 18 or later. Prebuilt binaries cover macOS arm64 and x64, Linux x64 and arm64, and Windows x64. npm installs only the binary for your machine, from a per-platform optional dependency such as @offline-protocol/cli-darwin-arm64, so keep optional dependencies enabled: do not install with --omit=optional or --no-optional.

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

Without a global installation:

npx -y @offline-protocol/cli --version

Use npx -y @offline-protocol/cli <command> for any command below. Install through npm; the crates.io package is a placeholder, not the released CLI.

Changes in 0.2.6

The npm package metadata and README list support@offlineprotocol.com as the help contact.
offline init and new scaffolds start the local MCP server with @offline-protocol/cli@0.2.6.

Changes in 0.2.5

npm installs one platform binary, about 10 MB, instead of all five, about 50 MB. Keep optional dependencies enabled.
The developer session from offline login --email renews while you use the CLI, and offline logout signs it out.
On macOS and Linux, credentials are written atomically and owner-only. The local login callback limits request size and time.
Starter templates are licensed under MIT-0, and each generated README lists the license of every Offline Protocol package the project uses.
New scaffolds use @offline-protocol/id-react 0.2.0.

Run offline update to check for a newer release; it prints the upgrade command.

offline login
offline whoami --json

Login prints a confirmation code and opens https://dev.offlineprotocol.com/cli-auth. Choose the application, enter the code exactly as the terminal shows it and approve. Only approve a login you started yourself; after five wrong codes the login is cancelled. Each login creates a new application API key for that terminal. Organization keys are not accepted. The CLI receives the approval on a local callback at 127.0.0.1, on a free port chosen at login (set OFFLINE_CALLBACK_PORT to pin one), and also polls for it, so login completes even when the browser cannot reach the callback. Credentials are stored in ~/.offline/config.json; see what the CLI stores and sends. Use offline login --no-browser on a headless machine and complete approval from another browser. For CI, supply OFFLINE_API_KEY through your secret manager, or use offline login --api-key <application-api-key>. Keep keys out of source control and logs. offline login --email signs in with a one-time code in the terminal instead. It stores a developer session rather than an API key, and it is required for setup, orgs, apps and keys.

offline logout

Logout clears local credentials and revokes the key that login created. Keys you created in the portal, including one supplied with --api-key, stay active; delete them in the portal when they are no longer needed. After offline login --email, logout also signs out the developer session. That session lasts 30 days, renews while you use the CLI, and ends 90 days after sign-in at the latest.

What the CLI stores and sends

On your computer. offline login and offline login --email write ~/.offline/config.json (or $OFFLINE_CONFIG_DIR/config.json): the application API key, the developer session token from email sign-in, your email address, and your developer, organization and application IDs. The file is plain JSON, not encrypted and not in the system keychain. On macOS and Linux it is created owner-only (0600) and replaced atomically, ~/.offline is kept owner-only (0700), and a symlinked file or a directory other users can write to is refused. On Windows the file keeps the default permissions of your user profile folder. Anyone who can read the file can use the key. offline logout deletes it. To Offline Protocol. Sign-in requests, including this computer’s hostname as the device name shown when you approve the sign-in, and the developer API calls each command makes with your key or session. Hosted MCP receives the tool arguments your agent sends; it keeps rate-limit counters, keyed by a hash of the credential or by network address, in memory for about 90 seconds. Elsewhere. offline update asks the public npm registry for the latest version, only when you run it. Scaffolding and the local MCP tools that write projects run npm install and similar package-manager commands against the registries you have configured. Your MCP client receives tool inputs and results under its own terms. The CLI and the local MCP server send no usage analytics and no crash reports. Local MCP tools can write files in your project and run package-manager commands with your permissions, subject to your agent client’s approval settings; they are not sandboxed. The privacy policy covers the same points for every Offline Protocol service.

Initialize a project

From an existing JavaScript or TypeScript application directory containing package.json:

offline init --app-id app_your_application_id

For a new application, start with offline create; offline init requires an existing package manifest. This writes offline.config.json, an AGENTS.md section and, when the project has none, a .mcp.json that starts the local MCP server with npx -y @offline-protocol/cli@0.2.6 mcp serve. Review the generated changes with the rest of your application code. The configuration references the live JSON Schema. The application ID is public metadata; keep API keys outside these files.

Command	Purpose
`login`, `logout`, `whoami`	Manage credentials and inspect authentication state.
`setup`, `orgs`, `apps`, `keys`	Create or list organizations, applications and API keys from the terminal. Requires `offline login --email`.
`init`	Configure an existing project.
`create`, `add`	Scaffold a project or add packages.
`plan`	Plan an integration.
`doctor`, `update`	Check the toolchain and credentials, and check npm for a newer CLI release. `update` prints the upgrade command; it does not install it.
`registry`, `skills`	Inspect available packages and integration guidance.
`mcp serve`, `mcp install`, `mcp tools`	Run local MCP, print client configuration or list tools.
`completions`	Generate shell completions.

Use offline <command> --help for command options. There is no offline link command; project initialization uses --app-id, not --project-id.

Flag or variable	Effect
`offline whoami --verify`	Checks the stored API key and app ID against the developer API.
`offline logout --local-only`	Clears local credentials without revoking the key on the server.
`offline add <package> --dry-run`	Prints what would change without writing files.
`offline create --pol`	Adds Proof of Location (`@offline-protocol/pol`) to a React Native scaffold. Off by default.
`offline create --dir <dir>`	Writes the project to `<dir>` instead of `./<name>`.
`offline create -y`	Runs without prompts: accepts defaults and fails on missing required input. Same as `--yes`.
`OFFLINE_APP_ID`	Overrides the application ID saved in `config.json` when no `--app-id` is passed.
`OFFLINE_ORG_ID`	Overrides the organization ID saved in `config.json` when no `--org-id` is passed.

Start from a workflow

offline plan "<what you are building>" recommends a workflow, the packages it needs and the exact offline create command. Three workflows cover common enterprise integrations. Each scaffolds a React Native app on @offline-protocol/mesh-sdk 0.27.0 and needs no login:

Workflow	Scaffold	Guide
`local-handoff`	`offline create local-handoff --platform react-native --name my-app`	Local handoff
`backend-delivery`	`offline create backend-delivery --platform react-native --name my-app`	Deliver to a backend
`nearby-service`	`offline create nearby-service --platform react-native --name my-app`	Nearby service

Run offline registry list workflows for every workflow and offline registry list templates for the templates behind them.

Local MCP

offline mcp serve

The offline-protocol server uses stdio and requires no login or API key. Let your MCP client launch it. It provides 18 tools for packages, capabilities, workflows, examples, skills, templates, planning and scaffolding. Run offline mcp tools to inspect the list. scaffold_project, integrate_packages and init_project write local project files. These tools are available only in local mode. offline mcp install <client> prints configuration; it does not edit your client files. Supported names are claude-code, claude-desktop, codex, cursor and vscode. Use the manual configuration below for Windsurf.

Hosted MCP

Endpoint: https://mcp.offlineprotocol.com/mcp. Create an application key in the application’s API keys tab and send both headers:

Authorization: Bearer <application-api-key>
x-app-id: app_your_application_id

The app ID must match the key. Organization keys are rejected. Hosted mode offers the 15 read-only tools and cannot write files; use local MCP when your agent needs to scaffold or modify a project. Requests are limited to 60 per minute per key and 600 per minute per network address; a limited request receives 429 with Retry-After. The MCP endpoint only accepts POST requests from MCP clients. Opening https://mcp.offlineprotocol.com in a browser shows a short page explaining how to connect an agent; GET /mcp answers 405. The health endpoint reports service status.

Connect your agent

For per-client steps that run the pinned CLI through npx without a global installation, and for plugin availability, see Use Offline Protocol from your coding agent. Choose local or hosted mode for the same server name; do not configure both under offline-protocol in one client. Hosted examples use an application key supplied through the client’s environment, a secure prompt, or its private user configuration.

Client	Local setup	Hosted setup
Claude Code	`claude mcp add offline-protocol -- offline mcp serve`	HTTP command below.
Codex	`codex mcp add offline-protocol -- offline mcp serve`	TOML with environment bearer token.
Cursor	`.cursor/mcp.json` or `~/.cursor/mcp.json`	JSON with environment key.
VS Code	`.vscode/mcp.json`	JSON with a secret input prompt.
Windsurf	`~/.codeium/windsurf/mcp_config.json`	JSON in private user configuration.
Claude Desktop	`claude_desktop_config.json`	Use local mode; its configuration cannot send these headers.

Local:

claude mcp add offline-protocol -- offline mcp serve

Hosted, with OFFLINE_API_KEY set in your environment:

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

The command expands the key into the client configuration. Keep that configuration private. For a project .mcp.json that retains an environment reference, use:

{
  "mcpServers": {
    "offline-protocol": {
      "type": "http",
      "url": "https://mcp.offlineprotocol.com/mcp",
      "headers": {
        "Authorization": "Bearer ${OFFLINE_API_KEY}",
        "x-app-id": "app_your_application_id"
      }
    }
  }
}

Local, in ~/.codex/config.toml:

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

Hosted, in the same file:

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

Set OFFLINE_API_KEY in the environment used to start Codex.

Use .cursor/mcp.json in the project or ~/.cursor/mcp.json.Local:

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

Hosted, with the key in the environment used to start Cursor:

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

Use .vscode/mcp.json.Local:

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

Hosted, with a secret input prompt:

{
  "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_your_application_id"
      }
    }
  }
}

Use ~/.codeium/windsurf/mcp_config.json.Local:

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

Hosted: replace YOUR_API_KEY in this private user file. Do not commit or share it.

{
  "mcpServers": {
    "offline-protocol": {
      "serverUrl": "https://mcp.offlineprotocol.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "x-app-id": "app_your_application_id"
      }
    }
  }
}

Choose Settings, Developer, Edit Config and add this to claude_desktop_config.json:

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

Use local mode. Claude Desktop’s configuration cannot send the headers required by the hosted endpoint.

Give the agent current instructions

Use the live agent setup prompt rather than a copied version. Then provide your application, platform and intended workflow using Build with an AI agent. The documentation page menu shares reading context; it is separate from the Offline Protocol MCP server.

Start here

Workflows

Examples and integrations

Operate and ship

Developer portal

Support

Offline Protocol CLI and MCP server

Install

Changes in 0.2.6

Changes in 0.2.5

What the CLI stores and sends

Initialize a project

Start from a workflow

Local MCP

Hosted MCP

Connect your agent

Give the agent current instructions

​Install

​Changes in 0.2.6

​Changes in 0.2.5

​Login and logout

​What the CLI stores and sends

​Initialize a project

​Start from a workflow

​Local MCP

​Hosted MCP

​Connect your agent

​Give the agent current instructions

Install

Changes in 0.2.6

Changes in 0.2.5

Login and logout

What the CLI stores and sends

Initialize a project

Start from a workflow

Local MCP

Hosted MCP

Connect your agent

Give the agent current instructions