> ## Documentation Index
> Fetch the complete documentation index at: https://www.offlineprotocol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs target Mesh SDK v0.27.0. Match the installed package and binding before generating code. Start at /getting-started/agents for task-specific reading paths.
> Call the company and product Offline Protocol, never Offline alone. Current packages: @offline-protocol/mesh-sdk 0.27.0 (React Native), @offline-protocol/id-react 0.2.0, @offline-protocol/id-react-native 0.3.3, @offline-protocol/pol 0.1.2 and @offline-protocol/cli 0.2.6. Canonical docs URLs start with https://www.offlineprotocol.com/docs.
> The Mesh SDK runs in a native app or gateway. A browser OfflineID SDK integration does not provide browser mesh transport. Local mesh operation does not require a portal API key.
> Service RPC is signed plaintext in v0.27.0. Message delivery, durable local acceptance and backend commit are distinct outcomes. Use the workflow guide for the required application logic.
> Offline Protocol CLI 0.2.6 is on npm (@offline-protocol/cli, command offline). Its local MCP server runs with offline mcp serve and requires no login or key. Hosted MCP is at https://mcp.offlineprotocol.com/mcp with an application API key in Authorization: Bearer and a matching x-app-id; organization keys are rejected. Follow /tools/overview for setup and do not invent commands beyond it. MCP provides integration context and planning, not mesh execution; file-writing tools are local only.
> Phone Wi-Fi Direct and MultipeerConnectivity carry no data in v0.27.0. Use BLE or a provisioned relay. The receiver core ACKs before application persistence; use application acceptance for durable workflows.
> Proof of Location is Sepolia testnet witness evidence, not zero-knowledge proof or proof of presence. The geohash is public onchain. Read /proof-of-location/security before integration.

# Use Offline Protocol from your coding agent

> Connect Claude Code, Codex, Cursor, Gemini CLI, VS Code or another MCP client to Offline Protocol.

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](/docs/getting-started/quickstart).

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](mailto: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:

```bash theme={null}
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](/docs/tools/overview#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.

<Tabs>
  <Tab title="Claude Code">
    **Local MCP.** Run once:

    ```bash theme={null}
    claude mcp add offline-protocol -- npx -y @offline-protocol/cli@0.2.6 mcp serve
    ```

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

    ```json theme={null}
    {
      "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:

    ```json theme={null}
    {
      "mcpServers": {
        "offline-protocol": {
          "type": "http",
          "url": "https://mcp.offlineprotocol.com/mcp",
          "headers": {
            "Authorization": "Bearer ${OFFLINE_API_KEY}",
            "x-app-id": "app_your_application_id"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    **Local MCP.** Run once:

    ```bash theme={null}
    codex mcp add offline-protocol -- npx -y @offline-protocol/cli@0.2.6 mcp serve
    ```

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

    ```toml theme={null}
    [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:

    ```toml theme={null}
    [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" }
    ```
  </Tab>

  <Tab title="Cursor">
    **Local MCP.** Add this to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "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:

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

  <Tab title="Gemini CLI">
    **Local MCP.** Add this to `~/.gemini/settings.json`, or `.gemini/settings.json` in your project:

    ```json theme={null}
    {
      "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`:

    ```json theme={null}
    {
      "mcpServers": {
        "offline-protocol": {
          "httpUrl": "https://mcp.offlineprotocol.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY",
            "x-app-id": "app_your_application_id"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code and Copilot">
    GitHub Copilot uses these tools in agent mode.

    **Local MCP.** Add this to `.vscode/mcp.json`:

    ```json theme={null}
    {
      "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:

    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other MCP clients">
    **Local MCP.** Most clients accept this `mcpServers` entry. Merge it into your existing servers instead of replacing them:

    ```json theme={null}
    {
      "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.

    ```http theme={null}
    Authorization: Bearer <application-api-key>
    x-app-id: app_your_application_id
    ```
  </Tab>
</Tabs>

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](/docs/getting-started/agents). 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](/docs/tools/overview).