@sentinel-watch-org/mcp-server

A Model Context Protocol server that lets LLM clients (Claude Desktop, IDE assistants, etc.) read and operate a Sentinel Watch customer account on the user's behalf.

Status: Phase 1 — read-only. See MCP_SERVER_PLAN.md in the repo root for the full roadmap.

Available tools (v0.1)

| Tool | Description | |---|---| | get_my_profile | Returns the calling identity (customer id, role, scopes, location scope). Use first to verify connectivity. | | list_my_tokens | Lists API tokens for the customer (manager+ only). Token plaintext is never returned. | | get_audit_log | Reads recent entries from the customer audit log. Filter by action, actor type, date range. | | get_balance | Returns current Sentino wallet balance + last sync time. | | get_report | Returns a customer reporting snapshot (events, watch hours, coverage, reward spend) for a given period. Parametric: granularity × scope (customer / cameras / single camera / location / events). | | list_locations | Lists all locations the customer owns. | | list_cameras | Lists cameras the customer owns. Optional locationId filter. | | get_camera | Returns a single camera's full configuration (rate, status, schedule, events, custom events). | | list_staff | Lists the customer's staff members and their roles. | | get_payout_history | Returns the customer's recent wallet ledger (credits + debits) with running balance. | | export_reports | Bulk export of any reporting snapshot as CSV (default) or JSON. Same parameters as get_report. Tighter per-hour rate limit. | | get_alert_config | Returns the alert routing configuration for a single location (channels, routes, quiet hours). Channel secrets are never returned — only a hasSecret flag. | | get_camera_alert_config | Returns a single camera's alert config plus the merged effective config (location defaults + camera overrides), with per-field source attribution. |

Write tools (update_camera_rate, update_alert_config, etc.) ship in Phase 2.

Setup

1. Generate an API token

In the Sentinel customer dashboard → AI Access → Create token.

• Choose scopes appropriate for read-only use (the v0.1 tools only need audit:read and staff:read).
• Copy the scs_live_… value immediately — it is shown only once.

2. Configure your MCP client

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sentinel": {
      "command": "npx",
      "args": ["-y", "@sentinel-watch-org/mcp-server"],
      "env": {
        "SENTINEL_API_BASE_URL": "https://app.sentinel-watch.org",
        "SENTINEL_API_TOKEN": "scs_live_REPLACE_ME"
      }
    }
  }
}

Restart Claude Desktop. The tools appear under the hammer/tools menu.

3. Try it

"Use sentinel to confirm what my token can do."

The model will call get_my_profile and respond with the customer id, role, and the scopes available to your token.

Environment variables

| Variable | Required | Default | Description | |---|---|---|---| | SENTINEL_API_BASE_URL | yes | — | Base URL of the Sentinel app, e.g. https://app.sentinel-watch.org. No trailing slash. | | SENTINEL_API_TOKEN | yes | — | A scs_<env>_… token from the customer dashboard. | | SENTINEL_REQUEST_TIMEOUT_MS | no | 15000 | Per-request HTTP timeout. | | SENTINEL_MCP_DEBUG | no | false | When true, writes diagnostic lines to stderr. Never logs the token (masked). |

Security model

• The API token is a bearer credential. Treat it like a password. Anyone with the token can act as your account within the granted scopes.
• Tokens are scoped, rate-limited, and audited server-side. See MCP_SERVER_PLAN.md §3 / §7 / §8.
• The MCP server does not persist anything on disk and does not log request bodies.
• All logs go to stderr; stdout is reserved for the MCP transport.

Local development

npm install
npm run typecheck
npm test
npm run build
SENTINEL_API_BASE_URL=http://localhost:3000 \
SENTINEL_API_TOKEN=scs_dev_xxxxx \
SENTINEL_MCP_DEBUG=true \
npm start

To exercise the server interactively, point a tool like the MCP inspector at the built dist/index.js.

Architecture

mcp-server/
├── src/
│   ├── index.ts          # stdio bootstrap
│   ├── config.ts         # env loading + validation
│   ├── client.ts         # undici HTTP client (timeouts, retries, error mapping)
│   ├── errors.ts         # stable error codes (matches API contract)
│   └── tools/
│       ├── index.ts      # registration entry point
│       ├── profile.ts    # get_my_profile, list_my_tokens
│       ├── audit.ts      # get_audit_log
│       ├── wallet.ts     # get_balance
│       ├── reporting.ts  # get_report
│       ├── fleet.ts      # list_locations, list_cameras, get_camera
│       ├── staff.ts      # list_staff
│       └── payouts.ts    # get_payout_history
└── test/                 # vitest

The MCP server is intentionally a thin protocol adapter. All authorization, rate limiting, spending caps, and auditing live in the Sentinel API — see MCP_SERVER_PLAN.md §7.