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¶
- 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. - The client makes an initial request with no credentials. The server answers
401with aWWW-Authenticateheader pointing at the discovery documenthttps://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. - A browser window opens so you can sign in at
app.hodeishield.comwith 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 inthird_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 returns429withRetry-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.