Use Offline Protocol from your coding agent

Connect your coding agent to the Offline Protocol MCP server. The agent can then find compatible packages, read integration guidance, plan an implementation and, in local mode, scaffold project files. It works on your code. It does not discover peers, operate devices or read device telemetry; build and test device communication with the Mesh SDK. The developer portal shows the same steps in each application’s Connect tab, under Agents, with your App ID filled in.

Choose how to connect

Option	Where it runs	Needs	Status
Local MCP	Your machine	Node.js 18 or later	Available
Hosted MCP	Offline Protocol hosted service	App API key and App ID	Available; cannot write files
Plugins	Your machine	Node.js 18 or later	Available for Claude Code, Codex, Cursor and Gemini CLI

The plugins package the local MCP server with the Build with Offline Protocol integration skill. They come from the public offline-protocol-agent-plugins repository and start the published CLI through npx, so they need no login:

# Claude Code
claude plugin marketplace add https://github.com/Offline-Protocol/offline-protocol-agent-plugins.git
claude plugin install offline-protocol@offline-protocol

# Codex
codex plugin marketplace add https://github.com/Offline-Protocol/offline-protocol-agent-plugins.git
codex plugin add offline-protocol@offline-protocol

# Gemini CLI
gemini extensions install https://github.com/Offline-Protocol/offline-protocol-agent-plugins

For Cursor, copy plugins/offline-protocol from that repository into ~/.cursor/plugins/local/offline-protocol and reload Cursor. The repository README also covers Cline and Devin. Configure the plugin or local MCP for a client, not both: each registers the server as offline-protocol. Local MCP starts the published CLI through npx, so no global installation is needed:

npx -y @offline-protocol/cli@0.3.3 mcp serve

The first launch downloads that release from npm; later launches use the npm cache. It needs no login or API key. scaffold_project, integrate_packages and init_project write local files and are available only in local mode. Hosted MCP runs at https://mcp.offlineprotocol.com/mcp. Send an app API key as a bearer token and the matching App ID in x-app-id. Organization keys are rejected. Hosted mode offers the 15 read-only registry tools and app_status, which reads the key’s application setup. Claude Desktop and Claude.ai cannot send these headers, so use the public read-only endpoint https://mcp.offlineprotocol.com/public/mcp there as a custom connector, or local MCP to scaffold or edit projects. See Hosted MCP for limits. Configure one mode per client under the offline-protocol name, not both. From CLI 0.3.0, local MCP also sets up your account after offline login --email. Its account tools create applications and API keys, register iOS and Android apps, set origins and features, and turn on development mode for simulators and Expo Go. Hosted MCP reads the setup with app_status and changes nothing. On the keyed endpoint app_status uses the app API key; on the public endpoint, when the setup tools are enabled on the server, the agent signs in with start_setup_login and finish_setup_login, which you confirm in the portal. Setup tools compares the two, and the agent quickstart walks through each step and its CLI command.

Set up your client

Replace app_your_application_id with your App ID. Keep API keys out of files you commit.

Local MCP. Run once:

claude mcp add offline-protocol -- npx -y @offline-protocol/cli@0.3.3 mcp serve

Or commit this as .mcp.json in your project:

{
  "mcpServers": {
    "offline-protocol": {
      "command": "npx",
      "args": [
        "-y",
        "@offline-protocol/cli@0.3.3",
        "mcp",
        "serve"
      ]
    }
  }
}

Hosted MCP. With OFFLINE_API_KEY set in your environment, a project .mcp.json can keep an environment reference:

{
  "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 MCP. Run once:

codex mcp add offline-protocol -- npx -y @offline-protocol/cli@0.3.3 mcp serve

Or add this to ~/.codex/config.toml:

[mcp_servers.offline-protocol]
command = "npx"
args = ["-y", "@offline-protocol/cli@0.3.3", "mcp", "serve"]

Hosted MCP. In the same file, with OFFLINE_API_KEY set in the environment used to start Codex:

[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" }

Local MCP. Add this to .cursor/mcp.json in your project, or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "offline-protocol": {
      "command": "npx",
      "args": [
        "-y",
        "@offline-protocol/cli@0.3.3",
        "mcp",
        "serve"
      ]
    }
  }
}

Hosted MCP. 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"
      }
    }
  }
}

GitHub Copilot uses these tools in agent mode.Local MCP. Add this to .vscode/mcp.json:

{
  "servers": {
    "offline-protocol": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@offline-protocol/cli@0.3.3",
        "mcp",
        "serve"
      ]
    }
  }
}

Hosted MCP. VS Code prompts for the key once and stores it:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "offline-api-key",
      "description": "Offline Protocol app 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"
      }
    }
  }
}

Claude directory. Open the Offline Protocol connector in Claude’s directory and choose Connect to add the public read-only endpoint.Local MCP. Choose Settings, Developer, Edit Config and add this to claude_desktop_config.json:

{
  "mcpServers": {
    "offline-protocol": {
      "command": "npx",
      "args": [
        "-y",
        "@offline-protocol/cli@0.3.3",
        "mcp",
        "serve"
      ]
    }
  }
}

Hosted MCP. Claude Desktop cannot send the headers the keyed hosted endpoint requires. Add the public read-only endpoint https://mcp.offlineprotocol.com/public/mcp as a custom connector, or use local MCP to scaffold or edit projects.

Local MCP. Most clients accept this mcpServers entry, including Gemini CLI (~/.gemini/settings.json) and Windsurf (~/.codeium/windsurf/mcp_config.json). Merge it into your existing servers instead of replacing them:

{
  "mcpServers": {
    "offline-protocol": {
      "command": "npx",
      "args": [
        "-y",
        "@offline-protocol/cli@0.3.3",
        "mcp",
        "serve"
      ]
    }
  }
}

Hosted MCP. If the client can send custom headers, point it at https://mcp.offlineprotocol.com/mcp over streamable HTTP and send both headers. Keep the key in private settings or a secret store.

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

Restart the client after changing its configuration, then check that offline-protocol is connected.

Try a first request

Ask your agent for a concrete integration, for example:

Add an encrypted local handoff to this React Native app. Explain the device requirements, choose compatible packages, and show how the receiving app will persist the handoff.

Give it your platform, SDK version and target devices, as described in Build with an AI agent. Then compile the changed application and test on the target devices; a successful agent session does not establish radio delivery. For the full command reference and the globally installed offline command, see CLI and MCP.

Start here

Workflows

Examples and integrations

Operate and ship

Developer portal

Support

Use Offline Protocol from your coding agent

Choose how to connect

Set up your client

Try a first request