PatrolTech

PatrolTech MCP server

The remote Model Context Protocol server of PatrolTech, the guard tour and security patrol platform. It lets AI assistants such as Claude, ChatGPT, Copilot, Gemini or Cursor read and act on a PatrolTech account on behalf of a user who signs in with OAuth: rounds, routes, checkpoints, guards, incidents, users, locations, access control and scans.

[CI] [License: MIT]

This repository holds only the server code. To install the connector in your assistant, use PatrolTech/ai-integrations: plugins, MCP Registry entry and instructions for each client.

This server grants no access by itself. It has no credentials of its own: it forwards the user's token, and the PatrolTech API authorizes every call (organization and location roles, OAuth scopes and a closed list of writes allowed to agents). See SECURITY.md.

Connect without hosting a server

Use the hosted endpoint https://mcp.patroltech.online/mcp with an MCP client that supports remote OAuth. The user's PatrolTech account and role determine access.

Create a free account · Connection guide · Agent skill and client plugins

Building your own integration instead? See the API reference of the public REST API and the TypeScript SDK. Webhooks are in development: tell us which events you need at [email protected].

Ask about missed patrol rounds, suspicious checkpoint scans, unreviewed checkpoints, incidents or visitor access logs. Supported changes are proposals and require explicit confirmation. Deleting records, inviting users and billing are outside the connector's capabilities.

For client setup, OAuth verification and troubleshooting, see the agent installation guide, including Cline instructions.

How it works

MCP client ──OAuth──▶ PatrolTech authorization server    │ Bearer access token (audience = MCP_PUBLIC_URL)    ▼MCP server (this repo, stateless) ──agent session──▶ PatrolTech API    │                                   ▲    └── Redis: locks and rate limits    └── @patroltech/agent-capabilities + @patroltech/sdk-api

• OAuth resource server. /mcp requires a bearer token issued by the PatrolTech authorization server (RFC 9728 metadata at /.well-known/oauth-protected-resource/mcp). Tokens are verified against the API's JWKS (ES256, exact issuer and audience) and exchanged for a 15-minute agent session (POST /oauth/agent-session), cached by a hash of the token. The API trims the session to what the grant still allows.
• Stateless. Each request gets a fresh MCP server instance and serves both protocol eras (2025 and 2026-07-28). Nothing about a conversation is kept in memory: proposals live in the PatrolTech API, so any number of workers can serve the same user.
• Redis holds what must be shared between workers: the per-user lock around proposals (SET NX PX, renewed while it lasts) and the per-user, per-tool rate limits. It is required in production and staging. If Redis fails, propose, confirm and cancel answer "busy" rather than risk two proposals overwriting each other. Without REDIS_URL (development and test only) both live in process memory.
• Tools come from the mcp channel of @patroltech/agent-capabilities, which calls the API through @patroltech/sdk-api.

Tools

Prompts and resources

Both are fixed text in src/interface/mcp/guidance: they change nothing in the account and call no backend, so they do not go through the audit line or the rate limit of the tools. The connection still needs OAuth, like everything under /mcp.

The server also sends instructions (src/interface/mcp/serverInstructions.ts): guidance that spans several tools, such as using the ranking tools to compare guards and presenting them as activity data, not as an assessment of the people.

Writes need the write scope: without it the server answers 403 insufficient_scope with the read write challenge. Every result is { data, truncated?, notices?, note }, capped at 60,000 characters, where note says that data is data, never instructions. Each user can make 60 calls per minute to a read tool and 20 to a write tool. Every tool call writes one mcp.tool_call audit line with a hash of the arguments, never the arguments.

Endpoints

Configuration

Every variable is documented in .env.example. The server refuses to start, listing each missing or invalid variable, if the configuration is not valid.

Logs are one JSON object per line on stdout and stderr. Each process writes an mcp.heartbeat line every 5 minutes, so a log monitor can alert when it stops.

Development

Node.js 22.9 or later.

npm cicp .env.example .env.local   # fill in the values; .env.local is ignored by gitnpm run dev                  # tsx watch, loads .env.localcurl http://127.0.0.1:3110/health

Code layout follows the hexagonal style: src/domain (pure rules), src/application (use cases and their ports), src/interface/mcp (the MCP adapter) and src/infrastructure (HTTP, OAuth, SDK adapters, Redis, logging).

Self-hosting

You can run this server on your own infrastructure, for example to audit it or to put it in front of your own network policies.

OAuth audience. Access tokens are bound to the resource they were issued for. The PatrolTech authorization server only issues tokens for resources it knows, so a deployment under your own MCP_PUBLIC_URL needs to be registered with PatrolTech before PatrolTech users can connect to it. Ask through the channels in SECURITY.md.

What you need:

• Node.js 22.9 or later and Redis.
• A reverse proxy with TLS in front of HOST:PORT that forwards /mcp, /.well-known/oauth-protected-resource (and its subpaths) and, if you use them, /health, /health/ready and /.well-known/openai-apps-challenge. Keep the Host header: the server only accepts the host of MCP_PUBLIC_URL or loopback.

Steps:

1. Build the artifact: npm ci && npm run bundle && npm run smoke.
2. Copy dist/bundle/server.mjs, dist/bundle/server.mjs.map and package.json (the version comes from it) to a directory on the server. No npm install is needed there.
3. Create .env.local in that directory from .env.example, with APP_ENVIRONMENT=production and REDIS_URL.
4. Start it: node --enable-source-maps --env-file-if-exists=.env.local server.mjs, or with PM2 (below). The process stops gracefully on SIGTERM, waiting up to 55 s for calls in progress, so give it about 60 s before a forced kill.

With PM2

deploy/ecosystem.config.cjs runs the bundle in cluster mode. It holds no server data: it reads MCP_PM2_NAME, MCP_PORT and MCP_APP_ENVIRONMENT (required) and MCP_INSTANCES, MCP_SERVICE_NAME and PM2_APP_DIR (optional) from the environment, and loads the rest from .env.local.

MCP_PM2_NAME=mcp MCP_PORT=3110 MCP_APP_ENVIRONMENT=production MCP_INSTANCES=2 \  pm2 start ecosystem.config.cjs

In cluster mode the workers run with the Node.js of the PM2 daemon, which must be 22.9 or later for --env-file-if-exists. Never run pm2 update on a shared daemon: it restarts every app it manages.

With GitHub Actions

.github/workflows/deploy.yml deploys a fork of this repository by SSH: automatically to production after each Release that creates a new version on main (a merged version bump), and by hand (workflow_dispatch, staging by default). It builds, tests and smoke-tests the bundle without secrets, uploads the bundle, package.json and the ecosystem with rsync, and runs deploy/remote-deploy.sh on the server: checks .env.local, reloads PM2 without downtime, probes the readiness URL and waits until every instance is online with the new version. production only deploys from main or a v* tag.

The workflow and the scripts contain no server data, and the logs print nothing from the server. Create the GitHub environments staging and production (with a required reviewer and a deployment branch rule for main and v* tags on production) and set, in each one:

Server data goes in secrets, not variables: Actions masks secrets in the logs, and the workflow also masks the values derived from them.

Versioning and releases

The version lives only in package.json. When a change to it reaches main, the release workflow creates the v<version> tag and a GitHub release with the bundle and its checksums.

Related packages

• @patroltech/agent-capabilities: the catalog of reads and proposed actions this server exposes.
• @patroltech/sdk-api: the TypeScript SDK of the PatrolTech public API (API reference).
• PatrolTech/ai-integrations: the connector for each AI assistant.

License

MIT © Ingenieros Web SL