Petra Security MCP Server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| AUTH_MODE | No | env reads PETRA_API_KEY; gateway requires X-Petra-Api-Key on each /mcp request and never falls back to PETRA_API_KEY. | env |
| LOG_LEVEL | No | Log level. | info |
| MCP_HTTP_HOST | No | Bind address when MCP_TRANSPORT=http. Defaults to 127.0.0.1. The container image sets 0.0.0.0. | 127.0.0.1 |
| MCP_HTTP_PORT | No | HTTP port. Defaults to 8080. | 8080 |
| MCP_TRANSPORT | No | Transport to use: stdio (default) or http. | stdio |
| PETRA_API_KEY | No | Petra API key. Required for stdio and AUTH_MODE=env; not read in gateway mode. | |
| CONDUIT_S2S_SECRET | No | HMAC secret required for HTTP, checked against X-Gateway-S2S on /mcp. Generate with openssl rand -hex 32. If empty or a known placeholder, the HTTP server logs an error and exits non-zero. | |
| MCP_ALLOW_INSECURE_DEV | No | Set to exactly 1 to start HTTP without CONDUIT_S2S_SECRET. Logs a warning, does not enforce X-Gateway-S2S, and binds 127.0.0.1 only. Local development only. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
| logging | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| petra_list_tenantsA | List every client tenant (Microsoft 365 customer) in the Petra organization, alphabetically, with its Petra tenant ID, Microsoft tenant ID, onboarding date and paused flag. Start here to find the tenantId other petra_* tools take. Removed tenants are excluded; paused tenants are included unless includePaused is false. |
| petra_get_usageA | Get the whole-organization Petra billing snapshot in one call: for every tenant, the service (Monitoring or Autopsy), billableStatus (Trial, Active, NFR, Deleted), totalLicensedUsers, billableUsersThisMonth, proratingPercentageThisMonth and firstBillableDate, plus totals across the returned tenants. Use for invoice reconciliation against the PSA. |
| petra_list_billable_usersA | List the individual billable users for ONE tenant (users with an assigned Microsoft license that are not deleted), with display name, UPN, mail, enabled flag and license SKU IDs, plus totalBillableUsers and projectedBillableUnitsThisMonth. This is the user-level detail behind petra_get_usage. A Microsoft tenant ID is resolved to the Petra tenant ID automatically. |
| petra_list_incidentsA | List Microsoft 365 identity-compromise incidents Petra detected (account takeovers, BEC), newest first: compromised user, occurred/created time, remediation status, whether the attacker is still live, dwell time, and the phishing email that led to it. Omit tenantId to search every tenant in the organization. Petra only alerts on real compromises. |
| petra_get_incidentA | Get one Petra incident by its ID, with full user and phishing-email detail. Petra has no single-incident route, so this searches the newest 500 incidents (pass tenantId to reach older ones). |
| petra_get_failed_attacksA | Get the BLOCKED (failed) attack summary for one tenant: total count, counts by origin country, a daily breakdown by attack type (e.g. PASSWORD_SPRAY, LEGACY_AUTH), and the most-targeted users with the countries their attackers came from. Defaults to the last 30 days. Petra rate-limits this route heavily, so results are cached for 5 minutes. |
| petra_list_posture_reportsA | Get completed Microsoft 365 security posture reports: score and grade (with previous score/grade on follow-ups), control rollup (secure, fixed, open, drifted), the Global Administrators review (count, MFA strength, password age), top risks, and every check with its status, severity, current state and suggested fix. By default returns the latest report per tenant. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 7 tools
Each tool targets a clearly distinct resource or action: tenants, org-level usage, per-tenant billable users, incidents, incident detail, failed attacks, and posture reports. The billing-related tools overlap conceptually but are clearly separated by aggregate vs. user-level scope, and list vs. get incident tools have an explicit summary/detail boundary.
All tools use a consistent snake_case verb_noun pattern with the same petra_ prefix. The verbs are predictable list/get pairs, and no mixed naming conventions appear.
Seven tools is well-scoped for a read-only security and billing reporting server. Each tool covers a meaningful surface area without excessive fragmentation.
The surface covers the core reporting lifecycle: tenant discovery, usage, user-level billing, incidents, blocked attacks, and posture reports. Minor gaps exist around per-tenant aggregate usage, explicit report retrieval beyond defaults, and remediation/write operations, but agents can largely work around these.