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	Application API key and app ID	Available; cannot write files

The plugins package the local MCP server with the Build with Offline Protocol integration guidance. They are being validated client by client. 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 application 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. 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 application’s 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"
      }
    }
  }
}

Local MCP. Add this to ~/.gemini/settings.json, or .gemini/settings.json in your project:

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

Hosted MCP. Gemini CLI does not read environment variables in headers, so this entry holds the key. Keep it in ~/.gemini/settings.json, not a project file, and replace YOUR_API_KEY:

{
  "mcpServers": {
    "offline-protocol": {
      "httpUrl": "https://mcp.offlineprotocol.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_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 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"
      }
    }
  }
}

Local MCP. Most clients accept this mcpServers entry. 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"
      ]
    }
  }
}

For Claude Desktop, choose Settings, Developer, Edit Config. For Windsurf, use ~/.codeium/windsurf/mcp_config.json.Hosted MCP. Point the client at https://mcp.offlineprotocol.com/mcp over streamable HTTP and send both headers. Keep the key in private settings or a secret store. Claude Desktop cannot send these headers; use local MCP there.

Authorization: Bearer <application-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