Skip to content

MCP server

HodeiShield hosts an MCP server — the open protocol an AI assistant uses to call external tools — at https://mcp.hodeishield.com/mcp, using the MCP specification's "streamable" HTTP transport. There is nothing to install: point your MCP client at that URL and your assistant gains read-only visibility into your tenant's data.

Read-only, and proposals a person approves

None of the thirteen read tools change anything, and neither do the two proposal tools: propose_action only records a proposal that a person of your organisation must approve in the console (see Proposals). Each tool maps to an operation of the public /v1 API: the MCP server never touches the database directly, it only calls that API with your own identity.

Plan requirement

The MCP server is available on the Operate and Enterprise plans. If your tenant is on a lower plan, the authorization screen says so and no access token is issued for this resource. The plan and the licence are checked again on every tool call: if the tenant moves to a lower plan, or its licence is suspended, revoked or expires, the next call is refused with 403 (MCP_TIER_INSUFFICIENT or LICENCE_INACTIVE). While your organization's beta is running, the MCP server is included whatever your plan: the beta gives full access (the Enterprise tier), also to the client tenants of an MSSP in the beta.

Connecting

  1. In your MCP client (Claude.ai or another client that supports remote servers with OAuth), add a connector pointing at https://mcp.hodeishield.com/mcp. In Claude.ai this is added as a custom connector; the exact menu location depends on the client.
  2. The client makes an initial request with no credentials. The server answers 401 with a WWW-Authenticate header pointing at the discovery document https://mcp.hodeishield.com/.well-known/oauth-protected-resource (RFC 9728). The client reads that document and locates the authorization server without any manual configuration on your part.
  3. A browser window opens so you can sign in at app.hodeishield.com with OAuth 2.1 (authorization code + PKCE), using the same factors you already use — 2FA, a passkey, or SSO. The details of that flow, its scopes, and how to revoke an application's granted access are documented in Authentication and API keys; this page does not repeat them.
sequenceDiagram
    participant U as Your assistant / MCP client
    participant M as MCP server
    participant A as app.hodeishield.com
    participant V as /v1 API

    U->>M: Tool call, no token
    M-->>U: 401 + WWW-Authenticate (OAuth discovery)
    U->>A: Sign in (OAuth 2.1 + PKCE, with your 2FA/passkey/SSO)
    A-->>U: Access token
    U->>M: Same call, with the token
    M->>V: Read request with your identity
    V-->>M: Your tenant's data, within your scopes
    M-->>U: Result wrapped in an envelope

When you grant access you choose one of the tenants you can see in the console. What the assistant sees is exactly what you would see in that tenant, and only with the read scopes you granted. No tool accepts a tenant or organization identifier as a parameter — there is no way to ask it for another tenant's data. To work with another one, sign in again from your client and choose it.

Available tools

Thirteen tools, one per /v1 operation that answers JSON (the report file download, GET /v1/reports/{id}/download, is API-only: its answer is a PDF or a workbook, not data a model reads). List tools paginate with page and per_page (up to 50) and accept the same filters as the equivalent API operation — the full reference for each filter lives in the API reference.

Tool /v1 operation
list_vendors / get_vendor Vendors
list_alerts / get_alert Alerts
list_risks / get_risk Risks
list_compliance_controls Compliance controls per framework
get_framework_posture Posture of a compliance framework
list_evidence / get_evidence Evidence
list_endpoints Endpoints
list_reports / get_report Generated reports

list_compliance_controls and get_framework_posture take a framework parameter with one of these values: nis2, ens, iso27001, dora, gdpr, soc2, iso42001, nistcsf, pcidss, euaiact, hipaa, cmmc, cyberessentials, uaeia, sama, saudiecc, ndpa. Each framework requires its own read scope: granting access to nis2 does not give visibility into dora.

Proposals

propose_action asks HodeiShield to record a proposal of one action: create_task, schedule_vendor_scan or request_vendor_evidence. Nothing changes until a person of your organisation approves it in the console's proposals tray, which carries it out with the approver's own role; the person who proposed it cannot approve it. A proposal nobody decides expires after 7 days. An approved proposal can still end as refused: if, when it is about to run, the access that proposed it has been revoked or the tenant's plan no longer includes MCP access, it is not executed. get_proposal_status tells you what happened to a proposal made from the same application: proposed, approved, executed, rejected, refused (with a reason) or expired.

Proposing needs the act:propose permission, which the consent screen shows as "Propose actions that a person in your organisation will have to approve", and it must be requested together with the read permission of the area the action belongs to. If your connection was made without it, the tool says so; reconnect HodeiShield and allow it. At most 10 proposals per minute and 20 waiting for a decision, per application and user, and the same per user across all their applications.

Security model

  • Every result is wrapped in an envelope with source: "hodeishield:/v1" and an explicit note that it is data from your tenant, never an instruction for the assistant.
  • Indirect prompt injection. The text in a vendor record, a piece of evidence, or a note was written by a person or a third party — not by HodeiShield. A language model can end up treating that text as a command. The server cannot control what your MCP client does with the result: always review, with other tools, any action the assistant proposes based on data that came from here.
  • Third-party text is quoted. Free text in a result (names, titles, descriptions, notes) arrives inside <untrusted_data> elements, with control, zero-width and bidirectional characters removed and values longer than 2,000 characters truncated; an alert's source link is reduced to its host (source_host). The envelope lists those fields in third_party_fields. This makes the boundary visible to the model; it does not replace your review.
  • Its own rate limit. In addition to the API's quotas, the MCP server applies its own per-user limit of 60 requests per minute (the default of MCP_RATE_LIMIT_PER_SUBJECT_PER_MINUTE); exceeding it returns 429 with Retry-After.
  • Logs hold no content. The server records which tool was called and its technical outcome, never the call's arguments, its results or your token.

Next step