Connect an AI agent with MCP

Inspect configured monitoring connections, then add or rename a connection when you ask. You choose the services and permissions. Local use stays free and account-free.

A separate connection store under your control

The optional Node adapter runs on your machine or an isolated server you own. It does not read or synchronize the browser’s saved connections or the native app’s encrypted vault. Configure its approved service profiles yourself. Agent results omit service addresses, usernames, credentials and credential-store references.

MVP tools manage the adapter’s local connection configuration and read fixed health endpoints for Uptime Kuma, Proxmox VE, Proxmox Backup Server and Beszel. They cannot scan networks or change remote infrastructure. Proxmox/PBS/Beszel report endpoint reachability, not full resource health. Kuma reports the latest returned heartbeat statuses; a read timestamp is not a freshness guarantee.

Local stdio and the HTTP/OAuth protocol have isolated integration tests. A public shared connector endpoint and live ChatGPT/Cowork acceptance are not available. Remote use requires your own explicitly enabled HTTPS/OAuth bridge.

Set up local stdio

Use Node 24.15 or newer. Download the local connector and its SHA-256 checksum. Verify the checksum, extract it into a private directory and run npm ci --omit=dev --ignore-scripts inside the extracted package directory. Dependencies are pinned in the included npm shrinkwrap. An authorized source checkout can instead use pnpm install --frozen-lockfile.
Copy backend/mcp/config.example.json outside the checkout. Protect its directory with mode 0700 and the file with 0600. Replace the example destination with your own service and explicitly pin its IP addresses. Do not add shared operator or third-party targets.
Keep the local-owner member with the intended workspace and role. A reader can inspect; an editor with the write scope can save configuration. The operating-system process owner controls local stdio access.
Set the two absolute paths below and register the process in your MCP client. Keep private files and database backups out of source control and prompts.

export OBSERVEIFYNOW_MCP_CONFIG=/private/observe/config.json
export OBSERVEIFYNOW_MCP_DATABASE=/private/observe/connections.sqlite
node /absolute/ObserveifyNow/backend/mcp/src/index.mjs

A minimal owner configuration for a Kuma server you run on this machine:

{
  "workspace": "home",
  "members": [{"subject":"local-owner","workspace":"home","role":"editor"}],
  "profiles": [{
    "id":"home-kuma", "workspace":"home", "kind":"kuma",
    "url":"http://127.0.0.1:3001", "addresses":["127.0.0.1"]
  }]
}

For Proxmox/PBS, the owner can set a credentialFile pointing to a private mode-0600 local secret file containing the complete read-only Authorization header value. Tools never accept or return it. Normal HTTPS certificate validation remains enabled. Beszel’s health endpoint needs no credential; password login and certificate exceptions are outside this adapter.

Disconnect a local client by removing its MCP entry and stopping its adapter process. Its SQLite data remains local. Back it up privately before removing it; stopping a client does not erase saved connections.

Five tools, explicit permissions

context: Your verified subject, workspace, role, scopes and approved profile IDs/kinds. No destination or credential export.
list_connections: Read redacted metadata. Optional integer limit 1–20 and offset 0–50. Follow nextOffset until null.
get_connection: Read a named id, its profile, service kind, status-page slug and current version in your workspace.
read_connection_health: Read a configured id through a fixed service endpoint. Returns status and attempt time; failures omit private target details.
save_connection: Create or update only when requested. Requires read + write scopes and editor role. Accepts id, name, profileId, optional Kuma statusPage, integer expectedVersion, and UUID requestId. No URL, token or workspace argument is accepted.

Inspect my monitoring connections

Show my bridge identity and configured monitoring connections. Read each connection’s health and tell me which checks failed or need attention. Do not reveal service addresses or credentials, and do not change anything.

Add a connection, then verify it

Using the approved home-kuma profile, add a connection named Home monitoring with id home and status page default. Only create it if that id is absent. Then read it again and check its health. Keep credentials out of the answer.

{"name":"save_connection","arguments":{
  "id":"home", "name":"Home monitoring", "profileId":"home-kuma",
  "statusPage":"default", "expectedVersion":0,
  "requestId":"6acf118d-c839-43fe-9c0d-b5ecb85b8c73"
}}

To rename it, ask: “Read home, rename it to House monitoring using its current version, then read it again.” Use a new request UUID for each requested change. Retry identical inputs with the same UUID; changed replay inputs fail. Receipts last up to 24 hours or the latest 2000 requests. A stale version fails without overwriting. Undo a rename by saving the previous name at the current version. Switching an existing service profile, deletion and remote infrastructure writes are outside MVP.

Opt-in HTTPS and OAuth

There is no public hosted endpoint with access to your LAN. For a remote client, deploy a dedicated single-owner bridge behind trusted HTTPS at https://YOUR-BRIDGE/mcp. An approved private tunnel can provide reachability only when the client supports that route; it does not replace OAuth. Shared ObserveifyNow identity/billing servers never receive your service configuration or readings.

The adapter is an OAuth resource server, not an identity provider. The deployment owner must connect an established maintained authorization server, register public clients with exact redirect URIs, and configure issuer, resource, JWKS and authenticated introspection URLs using secret-store references. HTTP mode fails closed without that configuration. Start it with node src/index.mjs --http; the default listener is loopback port 3341.

Protected-resource discovery lives at /.well-known/oauth-protected-resource/mcp. Its 401 challenge identifies the configured issuer. That issuer must publish authorization-server/OIDC discovery and support authorization code + PKCE S256, exact redirects, state/CSRF and issuer checks, resource binding, single-use short-lived codes, refresh rotation and revocation. API keys and browser session cookies do not establish direct ChatGPT OAuth compatibility.

Read scope: observe:connections:read. Optional write scope: observe:connections:write. Consent must show the account/workspace and selected scopes. The owner maps the verified issuer subject to a workspace and role; knowing a connection ID never grants access. Every invocation checks membership, role and grant. The signed observe_workspace claim must match current membership, so old consent cannot move to another workspace. Opaque access tokens use live signed introspection (RFC 9701); its issuer, audience, signature and age are verified along with the active token’s issuer, resource, expiry and scopes. JWT access tokens, when supported by the issuer’s introspection, also require signature and expiry validation. Tokens are never forwarded to infrastructure targets.

Disconnect remote clients in the issuer’s connection settings and revoke their grants/refresh tokens. Remove their bridge membership for immediate local denial. Remove the client-side connection too. The next bridge request must fail; a client-side removal alone is not proof of server revocation. Do not enable a remote deployment until its real issuer consent, registration and disconnect journey has been verified.

Client recipes and compatibility

Compatibility record updated 20 October 2026. The local Codex result below is a real model-driven test; separate SDK protocol tests cover transport behavior. No connector is installed into your real account automatically.

Codex: model-tested local stdio

On 20 October 2026, Codex CLI 0.163.0 with gpt-6.1-sol, high reasoning and default service tier used the public connector download to list an empty store, save a requested synthetic connection, read it and check its health. A second fresh client and adapter read the saved name and version 1, then checked health again. All nine tool calls succeeded; the SQLite checksum stayed identical across the read-only restart.

This test used only a disposable loopback Kuma fixture and a separate connection store. It does not establish real monitoring-provider coverage, browser or Tauri vault access, or production HTTPS/OAuth compatibility. The tested version 0.1.0 archive had source fd8b1d313ec186accdc7e235acf30b0c77bd1578 and SHA-256 2a1d77ba5e0baecabcf655631ec9536fb3b32d77140d98993185e8ba0b326063. This dated result applies to that archive; the current release manifest identifies today’s download.

Complete local setup, then register the process with its private configuration paths. ObserveifyNow needs no account; Codex uses your existing provider login. These registration commands add a persistent entry to your Codex configuration:

codex mcp add observeifynow \
  --env OBSERVEIFYNOW_MCP_CONFIG=/private/observe/config.json \
  --env OBSERVEIFYNOW_MCP_DATABASE=/private/observe/connections.sqlite \
  -- node /absolute/ObserveifyNow/backend/mcp/src/index.mjs
codex mcp get observeifynow

Repeat the synthetic read, save and restart check

Start this optional Python 3 fixture in its own terminal. It binds only to an available loopback port and serves one synthetic heartbeat path. Stop it with Ctrl+C when finished.

from http.server import BaseHTTPRequestHandler, HTTPServer

class SyntheticKuma(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path != "/api/status-page/heartbeat/default":
            self.send_error(404)
            return
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(b'{"heartbeatList":{"1":[{"status":1}]}}')
    def log_message(self, *args):
        pass

server = HTTPServer(("127.0.0.1", 0), SyntheticKuma)
print("Synthetic profile URL: http://127.0.0.1:" + str(server.server_port), flush=True)
server.serve_forever()

Save and run the snippet as python3 synthetic-kuma.py. Use a fresh private configuration and an unused SQLite path. In the setup example, replace only the home-kuma URL’s port with the printed port; keep its pinned address 127.0.0.1. Do not use an existing owner store or a real provider for this check.
Connect Codex using those fresh paths. Start it with codex --model gpt-6.1-sol -c model_reasoning_effort='"high"' -c service_tier='"default"'. Use only the ObserveifyNow tools and the prompts below. If the exact model or existing login is unavailable, stop; this recipe does not require an API or account fallback.
Stop the first Codex client and its adapter, then start a fresh client with the same configuration and SQLite path. Ask only for the saved connection and health. Confirm the same name and version 1; do not save again. Finally remove the test MCP entry, stop the fixture, and remove only your disposable files after inspecting the results.

Use only ObserveifyNow. Show context and list connections. Stop if the list is not empty. I request a connection named Synthetic check, id synthetic-check, using home-kuma and status page default. Create it with expectedVersion 0 and a new request UUID. Then read it and check its health. Do not reveal addresses or credentials.

Use only ObserveifyNow. Read synthetic-check and its health without changing anything. Report the saved name and version exactly as returned.

The recorded acceptance run used invocation-only overrides to disable unrelated tools and MCP servers while preserving global configuration and login credentials. Maintainer run receipts and the fully isolated CLI reproduction require repository access; the connection steps and synthetic check above are public.

For an accepted owner HTTPS deployment, use codex mcp add observeifynow --url https://YOUR-BRIDGE/mcp --oauth-client-id REGISTERED-PUBLIC-CLIENT, then codex mcp login observeifynow and review consent yourself. Remove with codex mcp remove observeifynow; also revoke remote grants. Remote Codex acceptance remains blocked pending an isolated production issuer/bridge and real consent, revocation, recovery and rollback checks. Register the exact callback displayed by Codex before login.

ChatGPT

Direct ChatGPT connections need reachable remote MCP and the owner’s interoperable OAuth route; local stdio is not a direct ChatGPT endpoint. Once the isolated HTTPS issuer/bridge has passed acceptance, open ChatGPT on the web, go to Plugins, select the plus button and Add custom MCP server. Enter the endpoint (or a supported Secure MCP Tunnel), choose OAuth with the registered client, and review consent yourself. Run the read prompt before requesting a save. Availability depends on the account/workspace. Current status: blocked pending isolated remote deployment and test identity consent.

Claude clients and Cowork

Claude Code can register a local stdio server with claude mcp add --transport stdio observeifynow --env OBSERVEIFYNOW_MCP_CONFIG=/private/observe/config.json --env OBSERVEIFYNOW_MCP_DATABASE=/private/observe/connections.sqlite -- node /absolute/ObserveifyNow/backend/mcp/src/index.mjs. Claude Code 2.1.303 command support was inspected; its client journey is documented-only. Cowork and Claude’s remote connectors connect from Anthropic’s cloud, including on desktop. Local Desktop stdio configured through claude_desktop_config.json is separate and unavailable in Cowork. After remote deployment acceptance, open Customize → Connectors → Add custom connector, enter the endpoint, select your preregistered OAuth client and complete your own consent. Team/workspace owner rules apply. Cowork acceptance remains blocked pending that isolated journey.

Hermes Agent

For a local process, add an entry to your isolated Hermes profile’s config.yaml:

mcp_servers:
  observeifynow:
    command: node
    args: [/absolute/package/backend/mcp/src/index.mjs]
    env:
      OBSERVEIFYNOW_MCP_CONFIG: /private/observe/config.json
      OBSERVEIFYNOW_MCP_DATABASE: /private/observe/connections.sqlite

For an accepted remote deployment use url, auth: oauth and your preregistered oauth.client_id, redirect_host and redirect_port matching the issuer’s exact callback. Run hermes mcp login observeifynow yourself. Remove/disable that exact server entry and revoke issuer grants to disconnect. Status: documented-only; no installed Hermes build or live journey verified. Record the exact version before testing.

Grok Bot

Cursor Grok Bot’s cloud connection is separate from Cursor IDE and cannot access a device-local adapter automatically. The exact client/account and custom OAuth route remain unverified here. Status: blocked. Next check: confirm that product/version’s supported remote connector setup, then test initialize, discovery, requested save, reconnect/read and disconnect against an accepted isolated HTTPS bridge. No forum workaround or Cursor IDE success establishes Grok Bot compatibility.

Privacy, limits and recovery

Only owner-approved service origins and exact IPs can be contacted. DNS answers must all match those pins, and the connection uses the same checked addresses. Redirects, metadata/link-local/multicast targets and arbitrary proxy calls are rejected. A private target is not permission to scan its network. Remote deployment also needs a destination-specific egress policy. TLS validation stays enabled.

Default budgets per minute: 60 cost units per principal, 120 per workspace, 10 saves per principal/workspace, and 30 incoming requests per socket peer including unauthenticated attempts. Health reads and saves cost 5; other reads cost 1. Four concurrent exchanges are allowed. The peer budget aggregates clients behind an ingress; forwarding headers cannot spoof identity or IP. Limits are configurable and finite. Run exactly one process/replica per volume; in-memory limits are not horizontally safe.

Requests are limited to 8 KiB, structured results to 16 KiB, and provider responses to 64 KiB. Service reads time out after 5 seconds. Up to 50 connections are stored per workspace. No subscriptions or background scans are exposed. Audit records contain subject/workspace/scopes, tool, outcome and a correlation ID, without tokens or private payloads. Keep audit storage private and bounded.

401: reconnect or ask the owner to check issuer, audience, expiry, revocation and membership.
403: review read/write scope and editor role; owners must approve any new Origin.
429: wait for Retry-After. Stdio callers wait for the configured next budget window. Do not retry in a tight loop.
Version conflict: read again and use the current version with a new request UUID.
Unavailable health: ask the owner to check exact destination/IP pins, normal TLS trust and read-only credentials. Private errors stay redacted.

Add one tool safely

Add a domain-specific tool in backend/mcp/src/tools.mjs with strict input/output schemas and accurate read-only, destructive, idempotency and open-world hints.
Use the shared per-invocation identity, membership, scope and role guard; derive workspace from verified membership. Reuse connection validation and approved profiles. Never accept arbitrary URLs, shell, SQL or grants.
Assign bounded cost, result size and timeout. Keep errors actionable without exposing targets or secrets.
Test real initialization/discovery, persisted read/write/reconnect, denial, isolation, replay/concurrency and limit recovery with a disposable fixture. Run pnpm --dir backend/mcp test and the milestone pnpm verify.
Update these public docs, the dated compatibility record and deployment contract before advertising support.

The official SDK is pinned to 2.3.1. It serves Streamable HTTP and stdio, with 2026-07-28 negotiation and stateless legacy 2025 protocol support. Initialization, discovery and tool calls are tested separately from deployed HTTPS and assistant acceptance.