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	Coming soon

The plugins package the local MCP server with the Build with Offline Protocol integration guidance. They are coming soon from a public plugins repository and cannot be installed yet. To join the preview, email support@offlineprotocol.com and name your client. Until your client’s plugin is available, use local MCP; it gives the agent the same tools. Local MCP starts the published CLI through npx, so no global installation is needed:

npx -y @offline-protocol/cli@0.2.6 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 tools. 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.

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.2.6 mcp serve

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

{
  "mcpServers": {
    "offline-protocol": {
      "command": "npx",
      "args": [
        "-y",
        "@offline-protocol/cli@0.2.6",
        "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.2.6 mcp serve

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

[mcp_servers.offline-protocol]
command = "npx"
args = ["-y", "@offline-protocol/cli@0.2.6", "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.2.6",
        "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.2.6",
        "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.2.6",
        "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.2.6",
        "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

​Choose how to connect

​Set up your client

​Try a first request

Choose how to connect

Set up your client

Try a first request