🪽 Gavriel MCP

Local MCP server (TypeScript) that exposes the Gavriel API — alarm monitoring system — as tools for AI agents (OpenCode, Claude Desktop).

Documentation

Requirements

• Node.js 20+ (tested with Node 22/24)

• Gavriel user credentials (app.gavriel.com.ar)

Installation

cd ~/proyectos/gavriel-mcp
pnpm install          # package manager: pnpm (see packageManager in package.json)
pnpm build
cp .env.example .env   # fill in GAVRIEL_EMAIL and GAVRIEL_PASSWORD

Configuration

src/config.ts reads these variables (from .env or the environment):

Server Roles (GAVRIEL_MCP_ROLE)

• full (default): all tools, including write tools (with confirm).

• lite: read access + core writes (tickets, interventions, conversations).

• readonly: read-only; write tools are not registered (they do not exist for the agent). Includes get and audit_logs, which are GETs.

Without the variable → full (current behavior). confirm remains in effect in all roles: role = availability, confirm = approval. The actual security role is the Gavriel user the server logs in with.

Service Role Configuration

The service role is defined in docs/PROPUESTA_ROL_SERVICIO.md. The recommended configuration is to use the MCP Service role (read-only) as the default.

Note: currently the MCP logs in with an Admin account (full CRUD). This is the current undesired state that the role proposal aims to replace, not a supported usage mode. Configuring the Admin account only makes sense as an interim step until the MCP Service role is created.

The JWT is cached in memory (never on disk) and renewed ~5 minutes before expiration or after a 401. The API renews the token through the x-new-token header, which the client automatically respects.

Secret Resolution

The server resolves password and trusted_device_token at startup, in this order (see src/secrets.ts):

1. System keyring (secret-tool, libsecret-tools package): most secure, and the recommended method.

2. Environment variables GAVRIEL_PASSWORD / GAVRIEL_TRUSTED_DEVICE_TOKEN (useful for local development outside OpenCode).

3. Legacy files (~/.secrets/gavriel-password and ~/.local/share/gavriel-mcp/trusted-device.json): last resort only, with an explicit warning on stderr.

The JWT is cached in memory (never on disk) and renewed ~5 minutes before expiration or after a 401. The API renews the token through the x-new-token header, which the client automatically respects. The trusted_device_token (valid for ~20 days and bypasses 2FA on subsequent logins) is also stored in the keyring.

Registering it in OpenCode

Install libsecret-tools (if not already installed) and store both secrets once, interactively (the value is requested through stdin and is not included on the command line):

sudo apt install libsecret-tools    # if needed (daemon: gnome-keyring)

secret-tool store --label="Gavriel MCP - password" service gavriel-mcp account password
secret-tool store --label="Gavriel MCP - trusted device token" service gavriel-mcp account trusted_device_token

The server reads them only from the keyring; the OpenCode config no longer needs the secret:

{
  "mcp": {
    "gavriel": {
      "type": "local",
      "command": ["node", "/path/to/project/gavriel-mcp/dist/index.js"],
      "environment": {
        "GAVRIEL_EMAIL": "user@example.com"
      }
    },
    "enabled": true
  }
}

Interim (until migration): if secret-tool is not installed, the server falls back to ~/.secrets/gavriel-password (chmod 600) with a warning. In that case the OpenCode config can still use {file:~/.secrets/gavriel-password} as it does today.

Tools

MCP names do not use a prefix. When using them from an OpenCode session, OpenCode prepends the server name: create_ticket is exposed as gavriel_create_ticket.

Read Operations (do not require confirm)

Write Operations — all require confirm: true

The gate is Phase 0, rule 2: if confirm is missing or false, the tool does not execute anything and returns a preview (method + path + body). If confirm: true, it executes and logs the operation in writes.log.

Important: always test first with confirm omitted/false and review the preview. Perform the first real execution of each tool in the presence of the operator — these are real production customer data.

Resources (semi-static catalogs, 1 h cache)

gavriel://catalog/... for event-types, event-codes, event-formats, protocols, intervention-categories, device-brands (and active ones), device-models, device-connection-types (and active ones), device-taxonomies, states, cities, jurisdictions, zones, ticket status/priority options, ticket-categories, activity type-options, event-types/gavriel-intervention, and company/type/technical.

Unimplemented Endpoints (Tier 3)

Write endpoints that exceed the approved risk profile (deletions, user/role management, monitoring activation, billing, catalogs, files) are inventoried in TIER3_PENDIENTE.md and are not implemented without explicit instruction.

Write Log

Every executed write operation is logged in ~/.local/share/gavriel-mcp/writes.log (JSONL): timestamp, tool, parameters, JWT user email, and API response (status + summarized body). This is in addition to Gavriel's own audit log (/audit/logs).

Deployment

It is not deployed: it is local, using stdio transport. It does not require Docker or the Hyper-V host.

Verification

pnpm typecheck   # types
pnpm build       # compiles to dist/
pnpm selfcheck   # quick offline core invariants suite (no network)
pnpm regression  # compares tool vs endpoint against the real backend (requires .env and network)

Security

• Secrets (password and trusted_device_token) live in the system keyring (recommended); the legacy ~/.secrets/gavriel-password (chmod 600) remains only as an interim fallback with a warning. The .env file in the repository (gitignored) is a local runtime fallback.

• The JWT is never persisted to disk.

• The confirm gate prevents accidental executions; control over when writes are used remains at the agent's skill/prompt level rather than being blocked in code (project owner's decision).

• Unparseable responses: occasionally the backend may return HTTP 200 with a truncated or invalid body. This tool detects it (writeStatus: "applied_response_unparseable"), logs the raw body, and re-reads the resource to verify the actual state. Do not assume success or failure for this status: check the returned verifiedState or re-query the resource.