teramind-mcp

# Teramind MCP Server

MCP server for [Teramind](https://teramind.co/)'s insider-threat/employee-monitoring API - computer inventory, agent (user) inventory, departments, alerts, anomaly-rule and behavior-policy configuration, and monitoring-profile metadata - for AI assistants and the WYRE Conduit gateway.

**This connector is PII-dense by construction** (insider-threat/employee-monitoring product) and requires security review before merge - see [Scope](#scope) and [Credential scope](#credential-scope-read-this-before-connecting-a-real-account) below.

## Authentication

Teramind authenticates with a JWT **Access Token**, self-generated per-account in the Teramind dashboard (User menu -> Access Tokens), sent as the `x-access-token` header. There is no OAuth flow.

Teramind's API is **per-customer-instance** (cloud or on-premise/private-cloud) - there is no shared multi-tenant base URL like most other connectors in this catalog. Every credential set also carries the customer's own instance URL (e.g. `https://yourcompany.teramind.co`). In gateway mode both arrive per-request via the `X-Teramind-Access-Token` / `X-Teramind-Instance-Url` headers; in local/stdio mode they're read once from `TERAMIND_ACCESS_TOKEN` / `TERAMIND_INSTANCE_URL`.

## Configuration

| Env var | Description |
|---|---|
| `TERAMIND_ACCESS_TOKEN` | JWT access token issued by the Teramind dashboard's Access Tokens menu. |
| `TERAMIND_INSTANCE_URL` | The customer's Teramind instance base URL, e.g. `https://yourcompany.teramind.co`. |
| `MCP_TRANSPORT` | `stdio` (default) or `http`. |
| `AUTH_MODE` | `env` (default, reads the vars above) or `gateway` (credentials arrive per-request via `X-Teramind-Access-Token` / `X-Teramind-Instance-Url`, injected by the Conduit gateway). |
| `CONDUIT_S2S_SECRET` | When set, the HTTP transport requires a valid `X-Gateway-S2S` header (Conduit sidecar auth) on every `/mcp` request. |
| `LOG_LEVEL` | `debug` \| `info` (default) \| `warn` \| `error`. |

## Tools

### Computers
- `teramind_list_computers` - list monitored computers (hostname, FQDN, MAC/IP, OS, monitoring status).
- `teramind_get_computer` - get full detail for a single computer.

### Agents (users)
- `teramind_list_agents` - list monitored agents (Teramind's term for a monitored employee/user identity): id, name, email, avatar, online status.
- `teramind_get_agent` - get full detail for a single agent.

### Departments
- `teramind_list_departments` - list departments (org-structure metadata).
- `teramind_get_department` - get full detail for a single department.

### Alerts
- `teramind_list_alerts` - list fired rule-violation events in a time window, optionally filtered by agent/computer/department.

### Anomaly rules
- `teramind_list_anomaly_rules` - list configured ML-based anomaly-detection rules (type, risk quotient, trigger conditions).
- `teramind_get_anomaly_rule` - get full detail for a single anomaly rule.
- `teramind_list_anomaly_rule_tags` - list the tags available to categorize anomaly rules.

### Behavior policies
- `teramind_list_behavior_policies` - list behavior policies (what activity type each policy watches and its match conditions).
- `teramind_get_behavior_policy` - get full detail for a single behavior policy.
- `teramind_list_behavior_policy_groups` - list behavior policy groups (the containers that organize behavior policies).
- `teramind_get_behavior_policy_group` - get full detail for a single behavior policy group.

### Monitoring
- `teramind_list_monitoring_profiles` - list monitoring profiles (which data types are configured to be captured, and for whom).

### Account
- `teramind_get_account` - get the authenticated account's own settings (credential sanity check).

## Scope

**This is a deliberately narrow, read-only v1 surface, scoped MORE conservatively than this catalog's usual bar given the sensitivity of an insider-threat/employee-monitoring product.** Teramind's documented API (fetched directly from its published Postman collection, `apidoc.dev.teramind.co`) has **239 operations** across dozens of product areas (monitoring, BI reporting, time tracking, scheduling, productivity classification, LDAP, task management, scheduling). This connector implements **16**: literal HTTP `GET` reads covering only computer/user/session inventory, department metadata, and rule/alert configuration. Every tool is classified `isAdmin: true` in the Conduit gateway regardless of verb, given the sensitivity of employee-monitoring data.

**No literal `GET` endpoint exists for session inventory.** Teramind's session data (`Sessions report`, `Login session` BI grid) is only reachable through `POST` query/grid-style endpoints, not a plain resource `GET` - documented here as a finding, not fabricated as a tool. Session data is out of this connector's v1 scope as a consequence, not a separate exclusion decision.

### Hard-excluded: anything that returns actual monitored content, or mints/reveals a credential - by name, even where the verb is `GET`

Per this connector's scope boundary, the distinction is: metadata **about** monitoring (who is monitored, when, what rule fired) is in scope; the actual captured content of what was monitored, or a mechanism to obtain a live credential, is **not**, regardless of read/write verb.

| Endpoint | Rationale |
|---|---|
| `GET /tm-api/agent/:id/avatar/:scale` | Returns the agent's avatar/headshot image - biometric-adjacent photo content. |
| `GET /tm-api/activity/email/:id/info` | Email-activity metadata (participants/subject) - content-adjacent; excluded alongside its two siblings below rather than judged separately. |
| `GET /tm-api/activity/email/:id/body-html-document` | Returns the full captured email body as rendered HTML. Raw captured content. |
| `GET /tm-api/activity/email/:id/body` | Returns the full captured email body. Raw captured content. |
| `GET /tm-api/player/settings` | Session-recording player/playback settings for a specific agent+computer. |
| `GET /tm-api/player-tags` | Annotations/bookmarks tied to recorded-session timelines. |
| `GET /tm-api/player-tags/timeline` | Timeline tags for a specific agent/computer's recorded sessions over a period. |
| `GET /tm-api/player/export-video/status/:id` | Status of a screen-recording video export job. |
| `GET /tm-api/player/available-video-data` | Enumerates which recorded video segments exist for a computer/period - an inventory of available screen recordings. |
| `GET /tm-api/report/export/download/:id` | Generic report-export download - the export could be of ANY report type this API supports, including keystrokes, emails, instant messages, or video, so it is excluded as a class rather than judged per export. |
| `GET /tm-api/report/export/status` | Status of a report-export job - same generic content-bearing concern as the download endpoint above. |
| `GET /tm-api/short-token` | Mints a new short-lived, live access token. Credential issuance, not content - held to the same bar as a credential-return endpoint in every other connector in this catalog. |
| `GET /tm-api/token` | Lists the account's active JWT token IDs - credential/session-management data. |

No `GET` endpoint anywhere in Teramind's documented API returns raw keystroke logs, chat/IM content, printed-document content, or social-media activity content - those are exclusively reachable through the `POST /tm-api/report/*/grid` and `POST /tm-api/wip/tma-query` (BI) families, which this connector excludes as a category below. **This connector's `GET`-only scope therefore rules out keystroke/screenshot/chat-content exposure by construction**, not merely by the per-endpoint judgment calls above - see [Credential scope](#credential-scope-read-this-before-connecting-a-real-account) for what this claim does and does not cover.

### Excluded by category (out of the named scope: computer/user/session inventory + rule/alert data)

| Category | Why excluded |
|---|---|
| Activities (aggregated activity) | Activity/productivity data, not inventory or rule/alert metadata. |
| BI / BI Filter (37 ops) | All `POST` query/chart endpoints; several return captured content (keystrokes, emails, IM, social media, printed documents, web search, console commands). |
| Reports / Report settings / Reports batch (~55 ops) | All `POST` grid/settings endpoints; several return captured content (keystrokes, emails, IM, printing, social media, console commands, video export). |
| Video export (remaining 2 ops) | `POST` write actions that generate exports of screen-recording content. |
| Time Tracking Reports, Time tracker tasks, Tasks, Schedule | Employee clock-in/task/shift-scheduling features, unrelated to monitoring inventory or rule/alert data. |
| LDAP | Directory-service connection config - out of scope, and a plausible vector for exposing bind-account details even as a plain read. |
| SMTP, Ingestion | Single `POST` write actions (send test email, create VoIP events); no read surface. |
| Shared lists | Rule-input datasets (e.g. keyword/URL watchlists referenced by rules) of ambiguous sensitivity - excluded as a judgment call rather than included by default. |
| Productivity Profile, `instance/tma-categories` | Productivity-classification taxonomy - arguably rule-adjacent, but not named in this connector's scope; excluded to stay tight rather than included as a stretch. |
| `instance/tma-state`, `time`, `license/usage` | Generic utility/status endpoints, none of which fit computer/user/session inventory or rule/alert data. |
| Every `POST`/`PUT`/`DELETE`/`PATCH` on Agent, Computer, Department, Behavior Policy, Anomaly Rule, Authorization, Monitoring Profile | Write, provisioning, enable/disable-monitoring, or account-mutation operations. Never implemented, regardless of verb. |
| Anomaly-rule / behavior-policy templates, tags-and-misc bundle, demo policy | Catalogs for AUTHORING new rules, not this org's actual configured monitoring - out of scope for a read-only inventory connector (`teramind_list_an