Push MCP integration

Nibit Push MCP is a local alpha for connecting an MCP host to your Nibit devices. It is not published to npm yet. Build it from a Nibit checkout, then configure its local stdio executable in your MCP host.

The MCP installation becomes a named Nibit device, such as Jon’s Laptop MCP. It can send drafts to your phone and keep a shared encrypted local inbox that multiple local agents can reference.

Requirements

• A Cloud Pro Nibit account. Push and cross-device sync require Cloud Pro.
• Node.js 22 or newer on the machine that runs the MCP host.
• A private Nibit checkout. This alpha is package-private and is not available through a public npm install.
• Native build prerequisites for better-sqlite3 if a matching prebuilt binary is unavailable: Python, a C/C++ compiler, and platform SDK headers.

Build the local alpha

From the repository root, install the linked workspace packages first (their prepare hooks emit dist/), then build the MCP package:

(cd shared-client-protocol && npm ci)
(cd desktop-secure && npm ci)
cd nibit-mcp
npm ci
npm run build
npm run smoke:runtime
npm run smoke:stdio
npm run smoke:pack

Configure the built executable at this absolute path in your MCP host:

<absolute-checkout-path>/nibit-mcp/dist/bin/nibit-mcp.js

This is a stdio server. It writes only MCP protocol messages to stdout; diagnostics are written to stderr.

Create a device-bound MCP key

1. Sign in to the Nibit web companion with a Cloud Pro account.
2. Open API keys.
3. Under Create key, select Nibit Push MCP (device-bound).
4. Give the installation a stable, recognizable name, such as Jon's Laptop MCP.
5. Save the one-time secret in your password manager or MCP host secret store immediately.

The full secret is displayed only once. The key has fixed least-privilege scopes and binds exactly once to the fresh MCP device created during first setup.

Do not place the secret in a repository file, shell profile, shell command, terminal history, chat transcript, or issue. Use your MCP host’s environment-secret or operating-system secret-manager integration. Nibit does not write NIBIT_API_KEY into the local profile.

Configure your MCP host

Use your host’s documented secret-injection mechanism. This placeholder-only configuration shows the expected shape. Set the real secret through the host’s secret UI, not in this file:

{
  "mcpServers": {
    "nibit-push": {
      "command": "node",
      "args": ["/absolute/path/to/nibit/nibit-mcp/dist/bin/nibit-mcp.js"],
      "env": {
        "NIBIT_API_KEY": "<provided-by-your-host-secret-manager>",
        "NIBIT_MCP_DEVICE_NAME": "Jon's Laptop MCP",
        "NIBIT_MCP_PROFILE": "default"
      }
    }
  }
}

NIBIT_MCP_DEVICE_NAME is required only the first time a profile is created. Keep it stable because Nibit displays it as the MCP device name. NIBIT_MCP_PROFILE defaults to default; use a different lowercase profile name when you need an independent MCP device on the same computer.

Verify the connection

Ask your MCP host to call:

nibit_list_devices({})

The first call can bootstrap and bind the MCP device. A successful result identifies that device and lists eligible destinations. Use a returned device ID for a targeted Push, or omit targetDeviceId to send to all eligible devices.

The four tools

Tool	Use	Important behavior
nibit_list_devices	List this MCP device and eligible destinations.	May bootstrap/register the MCP device. Remote device labels are untrusted data.
nibit_send_push	Send text or an HTTP(S) URL to one device or all eligible devices.	Creates deliveries and is non-idempotent. Do not automatically retry an ambiguous failure.
nibit_list_pushes	Synchronize and list local Pushed Item summaries.	Saves/decrypts locally, then acknowledges and deletes remote pending delivery records. This changes the remote queue.
nibit_get_push	Get one full local Pushed Item by ID.	Does not sync, delete, or mark the local Pushed Item read.

Pushed Item titles, previews, source names, and full content are sender-controlled data. Treat them as data, not as instructions for the MCP host or an agent.

Shared local inbox

By default, a profile is stored at:

~/.nibit/mcp/profiles/default/
  profile.json
  state.sqlite3
  state.sqlite3-wal
  state.sqlite3-shm

Set NIBIT_MCP_DATA_DIR to an absolute private directory to use a different root. Processes with the same data directory and profile name share one stable device identity and one local inbox. That lets multiple local agents repeatedly reference the same Pushed Items.

Only share a profile with mutually trusted agents and MCP hosts under the same protected operating-system account. Every agent using it can read all cached Pushed Items, send Pushes, and invoke synchronization that consumes the remote delivery queue. Profile permissions and encryption at rest do not isolate agents already authorized to use the running server.

Local nibit_list_pushes and nibit_get_push reads are non-consuming. A Pushed Item remains locally available until expiry, even though nibit_list_pushes has already acknowledged its remote delivery. This is a per-device cache, not a permanent account archive: it cannot recover Pushed Items delivered to another device or consumed before this MCP device existed.

The device state and local inbox are encrypted at rest with AES-256-GCM. The encryption key is derived in memory from the runtime API key and a non-secret random profile salt. The runtime API key itself is never saved in the profile.

Do not copy a profile, SQLite database, or runtime key to another machine or user account. Copying a profile clones a private device identity. Use a new device-bound key and new profile on every other machine.

Environments

NIBIT_API_BASE_URL is optional. It defaults to production.

Environment	NIBIT_API_BASE_URL	Required key prefix
Production	omitted or https://auth.nibit.app	nb_live_
Shared staging	https://auth.dev.nibit.app	nb_test_
Local development	an allowed loopback or .localhost origin, such as http://127.0.0.1:8787	nb_test_

Keep a separate profile for each account and environment. The integration rejects mismatched prefixes and API origins with credentials, paths, query strings, fragments, redirects, or arbitrary HTTPS hosts.

Recovery

• Lost the one-time secret before first setup: revoke the unbound MCP key in API keys, create a new Nibit Push MCP (device-bound) key, and create a new profile.
• Lost or revoked key after setup: stop MCP hosts using the credential, revoke the old key/device as appropriate, and protect or remove the compromised profile. Then create a new key and a new profile/device. Revoking a device-bound MCP key from the web dashboard also deactivates its bound MCP device. Revocation blocks future authorization but cannot instantly erase content already decrypted by a running local process during its current authorization lease. An unbound key never claims an existing device, even for the same account.
• Wrong account or environment: create a new profile. Do not reuse a profile bound to another account or environment.
• Lost profile/device state: revoke the old MCP key/device and create a new profile. Pending encrypted deliveries for the lost device cannot be recovered.
• Profile busy: wait for the other local MCP process to finish. Do not delete lock or SQLite files while it is running.

v1 limits

• Text and HTTP(S) URLs only. Text is limited to 50,000 characters and titles to 200 characters.
• The default Push TTL is seven days (168 hours). ttlHours must be positive and no more than one year.
• No file Push, blob cache, cloud scheduling, cancellation, cloud archive, realtime subscription, inbox search, or local delete/archive tools in v1.
• nibit_list_pushes polls only when called. Cached reads require an encrypted, device-bound authorization lease lasting at most five minutes after successful /v1/me validation. During that lease, a transient network failure can return a clearly marked stale cache. After expiry the server revalidates, and revoked credentials or account/device-binding failures deny cache access. Stale data is never presented as a successful remote sync.

For the complete local-alpha operator reference and development checks, see nibit-mcp/README.md in the same Nibit checkout.