Telivy MCP Server
Read-only visibility into Telivy's security assessment API for MSPs: external surface scans, deep-scan risk assessments, device inventories, user exposure, PII summaries, and finding-level detail.
External (surface) scans: list scans with search/sort/pagination, get a scan by assessment ID, list its findings, fetch a single finding by slug, and pull breach/dark-web credential-exposure records for the scan's domains.
Risk assessments (deep scan): list assessments with status filters, get one by ID, list all deep-scan devices or fetch a single device, and check scan completion status across devices.
Identity exposure: list Microsoft 365 users with login status and MFA info, and Google Workspace users with login and 2SV status.
PII: get the PII exposure summary across all devices in a risk assessment.
Findings and progress: fetch top-level finding details by slug (e.g.
TYPO_SQUATTING,PERSONAL_EMAILS) and generate a risk progress report (new/resolved/regressed/open) comparing two scan timestamp groups.Agent info: get the latest deep-scan agent versions for Windows and Mac.
No write operations are supported — provisioning actions (creating/updating scans and assessments, rescan/uninstall, monitor settings) and binary report downloads are out of scope.
Allows retrieving Google Workspace user accounts with login and 2-step verification (2SV) status as part of Telivy's security assessments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Telivy MCP Server show me the latest external scan findings"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Telivy MCP Server
MCP server for Telivy's security assessment API for MSPs - external (surface) scans, deep-scan risk assessments, device inventory, M365/Google Workspace user exposure, PII summaries, and finding-level detail, for AI assistants and the WYRE Conduit gateway.
Authentication
Telivy authenticates with a single static API key, generated from the Telivy Portal (Account > Integrations). An OAuth2/Auth0 implicit flow also exists, but the API-key path is simpler and is what MSP integrations use, so that's what this connector uses. The key is sent as the x-api-key HTTP header.
Related MCP server: CyberQP MCP Server
Configuration
Copy .env.example and set the variables below. Leave CONDUIT_S2S_SECRET empty in the example; generate a real value with openssl rand -hex 32.
Env var | Description |
| API key issued by Telivy. Required for stdio and for HTTP when |
|
|
|
|
| Required for HTTP. HMAC secret checked against |
| Set to exactly |
| Bind address when |
| HTTP port. Defaults to |
|
|
/health and /healthz stay unauthenticated and do not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.
HTTP authentication
With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The check is verifyS2sHeader in src/s2s-verify.ts: the header value is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header is HTTP 401, before the Telivy API key is read.
TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
-H "X-Telivy-Api-Key: $TELIVY_API_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'In AUTH_MODE=gateway, /mcp also requires X-Telivy-Api-Key. That header is the only credential source for the request. AUTH_MODE=env still requires a valid X-Gateway-S2S header, then uses TELIVY_API_KEY from the environment.
Tools
External scans
telivy_list_external_scans- list external (surface) scans, with search/sort/pagination.telivy_get_external_scan- get a single external scan by assessment ID.telivy_list_external_scan_findings- list the findings for an external scan.telivy_get_external_scan_finding- get details for a single external scan finding by slug.telivy_get_breach_data- get breach records surfaced for an external scan's domain(s).
Risk assessments
telivy_list_risk_assessments- list deep-scan risk assessments, with search/sort/pagination/status filters.telivy_get_risk_assessment- get a single risk assessment by ID.telivy_list_risk_assessment_devices- list all deep-scan devices for a risk assessment.telivy_get_risk_assessment_device- get a single deep-scan device by ID.telivy_get_risk_assessment_scan_status- get scan completion status across all devices.telivy_list_m365_users- get Microsoft 365 user accounts with login status and MFA info.telivy_list_gws_users- get Google Workspace user accounts with login and 2SV status.telivy_get_pii_summary- get the PII exposure summary across all devices.
Findings, agent versions, and risk progress
telivy_get_agent_versions- get the latest deep-scan agent versions (Windows/Mac).telivy_get_finding- get top-level finding details by slug (e.g.TYPO_SQUATTING,PERSONAL_EMAILS).telivy_get_risk_progress- get a progress report (new/resolved/regressed/open findings) comparing two scan timestamp groups.
Scope
This is a v1, read-only MSP fleet/security-visibility surface, matching this wave's convention of scoping connectors to monitoring/visibility and deferring provisioning-style writes. Explicitly out of scope for now:
All write endpoints: creating or updating external scans and risk assessments,
rescan-all,uninstall-all, rescanning a single device,convert-to-risk-assessment, and updating monitoring settings. These are provisioning/destructive actions, not read-only visibility.The binary report-download endpoints (
GET .../external-scans/{id}/report,GET .../risk-assessments/{id}/report) - they return files, not the structured JSON this connector's tools deal in.GET /api/v1/security/risk-assessments/{id}/domain-change-preview- a preview endpoint for an in-flight domain-change write, out of scope alongside the write it previews.
They can be added as a follow-up if there's demand.
Development
npm install
npm run build
npm test
npm run lint # tsc --noEmitHTTP refuses to start until CONDUIT_S2S_SECRET is set:
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:httpLocal HTTP without a service-to-service secret binds 127.0.0.1 only and logs a warning. The image sets MCP_HTTP_HOST=0.0.0.0, so this bypass also requires that variable to be loopback (or unset). A non-loopback host makes startup exit:
MCP_ALLOW_INSECURE_DEV=1 npm run start:httpDocker
The image listens on 0.0.0.0 inside the container and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass a real S2S secret. In gateway mode the Telivy API key arrives on each request as X-Telivy-Api-Key; it is not read from the environment.
docker build -t telivy-mcp .
docker run \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-p 127.0.0.1:8080:8080 \
telivy-mcpCompose refuses to start when CONDUIT_S2S_SECRET is unset or empty, defaults AUTH_MODE to gateway, publishes 127.0.0.1:8080:8080, and does not set TELIVY_API_KEY:
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose upSingle-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses TELIVY_API_KEY:
docker run \
-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
-e AUTH_MODE=env \
-e TELIVY_API_KEY="$TELIVY_API_KEY" \
-p 127.0.0.1:8080:8080 \
telivy-mcpAvailable Tools
16 toolstelivy_get_agent_versionsA
Get the latest Telivy deep-scan agent versions available (Windows and Mac).
Inputs: no named parameters.
telivy_get_breach_dataB
Get breach records surfaced for an external scan's domain(s) (dark-web/credential exposure).
Inputs: id (required).
telivy_get_external_scanC
Get a single external scan by assessment ID.
Inputs: id (required).
telivy_get_external_scan_findingB
Get details for a single external scan finding by slug.
Inputs: id (required), slug (required).
telivy_get_findingA
Get top-level finding details by slug (e.g. TYPO_SQUATTING, PERSONAL_EMAILS).
Inputs: slug (required).
telivy_get_pii_summaryB
Get the PII exposure summary across all devices in a risk assessment.
Inputs: id (required).
telivy_get_risk_assessmentB
Get a single risk assessment by ID.
Inputs: id (required).
telivy_get_risk_assessment_deviceB
Get a single deep-scan device by ID.
Inputs: id (required), deviceId (required).
telivy_get_risk_assessment_scan_statusA
Get scan completion status across all devices in a risk assessment.
Inputs: id (required).
telivy_get_risk_progressA
Get a risk progress report comparing two scan timestamp groups for an assessment (new/resolved/regressed/open findings).
Inputs: id (required), currentTimestampGroup (required), compareWithTimestampGroup.
telivy_list_external_scan_findingsC
List the findings for an external scan.
Inputs: id (required).
telivy_list_external_scansB
List external (surface) scans - lightweight, agentless domain/email security assessments.
Inputs: limit, offset, search, agencyId, +2 more.
telivy_list_gws_usersA
Get Google Workspace user accounts with login and 2SV status for a risk assessment.
Inputs: id (required).
telivy_list_m365_usersA
Get Microsoft 365 user accounts with login status and MFA info for a risk assessment.
Inputs: id (required).
telivy_list_risk_assessment_devicesA
List all deep-scan devices for a risk assessment.
Inputs: id (required).
telivy_list_risk_assessmentsB
List risk assessments - deep-scan (agent-based) fleet security assessments, optionally filtered by scan status.
Inputs: limit, offset, search, agencyId, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools map cleanly to distinct resources and actions, with clear list/get pairs for scans, assessments, findings, and devices. The only notable ambiguity is between get_external_scan_finding and generic get_finding, since both retrieve finding-like details by slug.
All tools follow a consistent telivy_<verb>_<object> snake_case pattern, using only list and get verbs. Minor semantic differences like get_breach_data or get_risk_progress still fit the established naming convention.
At 16 tools, the set is one above the ideal range but each tool represents a distinct resource view or operation needed for the two main assessment workflows. It feels slightly heavy rather than bloated.
The external scan and risk assessment surfaces are well covered, including findings, devices, breach data, user accounts, PII, progress, and agent versions. Gaps include no direct listing of risk-assessment findings or a way to enumerate finding slugs without prior knowledge.
Maintenance
Related MCP Connectors
Scopable MSP API: clients, quotes, assessments, compliance, QBRs. OAuth 2.1, read-only or read-write
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Pay-per-call cybersecurity for AI agents: vuln scans, threat intel, compliance, code security.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to manage MSP-multi-tenant email security: organizations, domains, users, licensing, features, subscription packages, and email flow reporting.Apache 2.0
- AlicenseAqualityBmaintenanceProvides read-only visibility into CyberQP privileged access management data, including customer and account metadata, tenant event logs, and Just-In-Time account status and policies, for AI assistants.10Apache 2.0
- AlicenseAqualityBmaintenanceEnables AI assistants to query RoboShadow's Rubicon Platform Data API for read-only endpoint security, asset inventory, applications, users, vulnerabilities, and remediation status data.401Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to query an MSP's network monitoring data — tenants, discovered devices, networks, interfaces, configuration backups, alerts, performance statistics and billing usage — through multi-tenant, stateless Streamable HTTP with credentials supplied per request. Read-only by default, with optional alert dismissal and raw API access for changes.Apache 2.0