Ask your agentic AI to run a HAIEC Assurance scan.
Connect Cursor, Claude Code, Devin, or any MCP-capable agent to the HAIEC Assurance MCP server. Your agent operates the same canonical Assurance workflow every client uses — while HAIEC remains the source of evidence state and verdict truth.
Try this prompt in your agent
“Ask your AI to run HAIEC AI Assurance”
Copying the text only. Nothing runs until your connected agent sends it.
- Endpoint
- https://www.haiec.com/api/mcp
- Transport
- Streamable HTTP
- Auth
- Bearer HAIEC_API_KEY
- Surface
- One bounded tool per canonical operation
HAIEC is an external assurance service. A coding agent does not analyze your repository itself and must not modify application code to run HAIEC — it operates the Assurance services, and the verdict is computed by HAIEC, not the model.
Connect your client
One remote Streamable HTTP server, one scoped Bearer key. Pick your client.
Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).
// .cursor/mcp.json — or ~/.cursor/mcp.json for all projects
{
"mcpServers": {
"haiec": {
"url": "https://www.haiec.com/api/mcp",
"headers": {
"Authorization": "Bearer ${env:HAIEC_API_KEY}"
}
}
}
}The API key is created at /dashboard/api-keys and lives only in your private client config or environment. It is never pasted into a prompt and never sent to MCP tool arguments.
Your first Assurance run
The minimum path to a first eligible result. Telemetry, IAM, and workflow sources are optional later steps, not prerequisites.
- 1Create your keyAn Assurance Agent API key at /dashboard/api-keys defines your tenant and scopes. The key is never pasted into a prompt.
- 2Run haiec_preflightReturns ready, per-check truth, and the exact required or optional user actions (GitHub App install URL, AI System selection, key scopes, evidence binders). Preflight is read-only and never runs an evaluation.
- 3Choose one AI System and one eligible sourceThe agent asks you to pick the exact system when more than one applies, and reports any permission or source-readiness gap instead of inventing readiness.
- 4Approve and run haiec_run_assuranceThe agent explains the exact run and asks once. It passes a caller-generated idempotencyKey so retries replay, never duplicate.
- 5Inspect the canonical resulthaiec_get_agent_audit and haiec_get_master_report return the same bounded report the dashboard and PDF render, with established facts, open items, and links to the rendered artifacts.
A static source run needs only the key, an AI System, and a verified Source Asset. If a finding needs authority, deployment, or runtime evidence to resolve, the result states that gap explicitly rather than silently upgrading the claim.
Optional evidence connections
Grouped by the question each source helps answer. Each is an independent qualified input, not a single connector and never a prerequisite for a code-level run.
Source & code
GitHub App repository analysis (recommended remote path), local or CI scanner (preview), authorized runtime endpoint.
Source capability is not observed execution.
Cloud identity & authority
AWS IAM and policy evidence via the monitoring workspace.
Partial authority evidence only. Unmodeled resource, endpoint, and session policies mean AWS observation never produces a canonical effectively-granted assertion on its own.
Cloud operational sources
AWS AgentCore capability probes and CloudWatch log reads, bounded to an exact account, region, credential, and declared window.
Adapter availability is not evidence any account is connected; nothing implies broad account inventory or on-target enforcement.
Telemetry & observed
Self-service OTLP intake for traces, metrics, and logs through a scoped token and generated collector template.
A generated collector config is not a verified live collector; a received signal is not an evaluated effect.
Business workflow evidence
ServiceNow AICT, Agent Studio, and approved Table API reads with credentials and ACL preflight.
Read-only bounded surfaces; no approval-ticket writeback or comprehensive SNOW inventory.
Structured & human evidence
Typed intake profiles for selected structured records and human-attested evidence, behind explicit upload consent and a configured binder.
An ingestion receipt means evidence was ingested; only a new Evaluation closes a gap.
Provider admin reporting for OpenAI and Anthropic cost/usage is a separate AI Inventory pathway at /ai-inventory. Those keys do not grant MCP access. Customer-native data gathering and operational coverage beyond these surfaces is scoped through an Enterprise engagement.
Which source helps next?
Pick the question you are trying to answer.
GitHub remote source analysis
Static analysis of an authorized repository traces supported agent, tool, and handler relationships to a consequential operation.
Still unestablished: Does not establish that the action executed, was authorized, or produced an effect.
GitHub source setupThis advisor makes no tenant API calls. Actual availability depends on your connected sources, credentials, and plan. Run haiec_preflight or haiec_list_connectors for your exact state.
How sources support HAIEC
Two lanes feed one canonical result. Your agent calls MCP tools and reads the bounded evaluation. Optional sources feed qualified evidence through the intake layer into source-aware views. Neither lane is a prerequisite for the other, and no source connection is required for a first source-level run.
Agent lane
Your agent
→ haiec MCP tools
→ canonical Assurance run
→ Agent Audit, Master Report, Dashboard
Source lane
Optional evidence sources
→ bound intake + qualification
→ source-aware evidence views
→ attach to a new Evaluation when asked
HAIEC evaluates five independent evidence planes: Requested, Policy Authorized, Effectively Granted, Code Capable, and Observed. Each is a distinct kind of fact, not a mandatory step, and a read-only source observation never implies an executed control or enforcement.
An Assurance BLOCK disposition is a canonical verdict within evaluated scope, not proof of native target-side enforcement.
How the agent operates HAIEC
A deterministic sequence — the same one every client follows.
- 1DiscoverPreflight the tenant, AI System, controls, evidence gaps, results, replay status, and any existing investigation.
- 2InvestigateUse the IDE agent’s permitted local tools; preserve source references, versions, timestamps, hashes, supporting facts, contradictions, and limitations.
- 3Collect + normalizeChoose an existing supported intake contract; typed profile failures never silently fall back to generic.
- 4PreviewShow Provided by, Normalized using, destination, case binding, sources, counts, facts, hypotheses, redactions, and limitations.
- 5Confirm + submitAsk once about that exact batch, then call the canonical intake tool with userConfirmedUpload: true.
- 6ReceiptReturn producerRunId, accepted/rejected counts, failures, bindings, qualification limits, and what remains unverified.
- 7Re-evaluateAttach the receipt to a new Evaluation only when requested; historical evaluations never change.
- 8Explain next actionSeparate HAIEC-established facts, AI interpretation, and the proof boundary or responsible next step.
Re-running the same source analysis does not close a gap that requires policy, IAM, deployment, identity, telemetry, or other external evidence. The agent should follow the deterministic resolution category returned by HAIEC.
Approval contract
Before a supported write, upload, runtime test, source change, or other consequential operation, the agent explains the exact action and asks the user to approve it. For an evidence upload, the agent first shows one readable preview of the exact outbound batch, then asks once; only after the user confirms may it pass userConfirmedUpload: true.
Evidence-upload confirmation authorizes sending that batch to the configured binder. It is not a UCP approval receipt, policy approval, runtime authorization, production-change approval, or proof that a gap is closed.
For this build, user confirmation in the IDE is accepted as the workflow approval signal. This is an execution acknowledgement; it does not independently prove that a production action had path-bound human approval at runtime.
Discovery
Machine-readable entry points:
/.well-known/haiec-capabilities.json— capability manifest (operations, source modes, statuses)./openapi/assurance-v1.yaml— the formal API contract.GET /api/v1/systems— runtime discovery of AI Systems (and…/evaluation-sourcesfor verified sources).GET /api/v1/evidence/binders— discovery of configured evidence destinations for the intake routes./api/mcp— the HAIEC Assurance MCP server (Streamable HTTP, Bearer API key).
HAIEC Assurance MCP
MCP is the preferred surface for AI IDEs and agents. It exposes the same canonical operations as the REST API — one bounded tool per operation — over a stateless Streamable HTTP transport. Authentication is the same HAIEC_API_KEY Bearer credential; the tenant is the key's organization and cannot be overridden by tool input.
- If HAIEC MCP is configured in the client → use the MCP tools.
- If only
HAIEC_API_KEYis set → use Assurance REST API v1 directly. - If neither exists → guide the user through the setup on this page.
- Start with
haiec_capability_guidewhen the user asks what HAIEC can do or names a goal rather than a tool — it returns the supported-goal index or, per goal, the canonical owner, evidence requirements, registry-derived readiness, relevant tools with required scopes, IDE vs cloud paths, approval steps, dashboard destination, limitations and next action. A capabilities question never triggers a scan. - Start with
haiec_preflightwhen setup state is unclear — it returnsready, per-check truth, and exact required/optional user actions with URLs (GitHub App install, AI System selection, API key scopes, evidence binders). Telemetry is never required forremote_assurance; a binder is required only forevidence_upload. haiec_run_assurancerequires a caller-generatedidempotencyKey— one UUID per intended run; retries with the same key+payload replay the same run.haiec_get_agent_auditincludesresolutionGroups— a deterministic grouping of the report's verification items into resolution groups (exactverificationNeededper group) — use it to explain what is established, what remains open, and the next action instead of asking the user one question per row.haiec_get_master_reportreturns the canonical Master Assurance Report product (bounded by default,detail:"full"for the complete projection) — the same product the dashboard HTML page and Master Report PDF render.links.html/links.pdfhand the user the rendered artifacts;haiec_get_reportremains the secondary Assurance Evidence bundle.haiec_get_dai_reportreturns the canonical Delegated Action Integrity read for one exactaiSystemId— the same nine-dimension projection the dashboard DAI page renders (six-hop evidence lanes, BROADER widening vs MISSING/UNKNOWN junctions, pending business rules,asOf, limitations). OptionalassuranceEvaluationIdbinds the read to that exact persisted evaluation of the same system. ThedaiEvaluationDigestis a deterministic digest — never a persisted evaluation ID. Missing delegation evidence is NOT_ASSESSED, never a violation.- Runtime:
haiec_runtime_preflightis a read-only safety plan (executable vs HELD categories, missing acknowledgements).haiec_run_runtime_testrequires literaluserConfirmedRuntimeTest: true+authorizationAcknowledged: truereflecting actual user statements — held categories never execute. Attach the resulting bound test to a NEW run viahaiec_run_assuranceattachRuntimeTestId. - MCP never accepts
organizationId, GitHub tokens, installation IDs, or arbitrary repository URLs — and never exposes the key back in tool output. - Evidence tools (
haiec_ingest_structured,haiec_ingest_logs) requireevidence:ingestscope plususerConfirmedUpload: true— call them only after the user explicitly approves the upload. - Setup tools: MCP can perform supported AI System and source setup actions (create system, register asset, bind a GitHub-App-listed repository, verify a source) after explicit user approval. Third-party authorization such as GitHub App installation may still require a browser handoff — HAIEC returns the exact destination rather than fabricating it. HAIEC never treats a caller-supplied repository URL or token as proof of trusted source authority.
- Per-client configuration: Cursor, Claude Code, Devin. The full tool list lives in the capability manifest.
Investigations — start, leave, return
An investigation groups evidence under user-declared states — "first evidence", "before the incident", "after the fix" — so HAIEC can reconstruct what was established at each point. The user never needs HAIEC's internal fields: the agent translates ordinary language into the explicit scenario binding on each ingestion. The IDE agent may inspect permitted local source, configuration, logs, commits, builds, and diagnostics, but its interpretation is not an observed event, HAIEC finding, or Assurance verdict. - "Start a HAIEC investigation" → haiec_preflight, then haiec_scenario_preflight, then haiec_prepare_scenario (one scenarioRunId per investigation; nothing persists until bound evidence exists). - "This is my first evidence" → ingest with the declared first state. - "Here is the next batch" / "start collecting the next state" → haiec_get_scenario_status returns the deterministic next state — never compute ordering from memory or timestamps. - "What changed?" → haiec_reconstruct_scenario and haiec_compare_scenario_states between declared states. - "Continue my HAIEC investigation" (days later, fresh client) → haiec_preflight → haiec_list_investigations → name the found investigation or present the choices, then continue with the exact scenarioRunId. Identity comes from persisted evidence, never conversational memory. - Live capture: haiec_prepare_scenario_capture returns env vars, a scenario-aware OTel Collector config, and test payloads — it persists nothing until you apply it and HAIEC verifies receipt through haiec_get_scenario_status. - Typed evidence: haiec_ingest_structured accepts an intakeProfile (kpi, alarm, api_transaction, policy, and the telecom profiles) that uses the same mapper as the matching REST intake route — you propose the profile from the file shape, the user approves, and a record that fails the typed schema returns the canonical error, never a silent generic fallback. - Large files: split into bounded chunks, keep the same scenario binding on every chunk, use a stable clientBatchKey per chunk (file digest + chunk index), upload in order, and retry only failed chunks — idempotent keys make replays safe. Investigations persist under the AI System's workspace (Investigations tab). An investigation records what evidence arrived and in what declared order — it is not an Assurance disposition. Only a new Evaluation establishes whether anything changed.
The user never needs to know internal identifiers (scenarioRunId, scenarioSequence), level presets (the optional TM Forum AL0/AL1/AL2 vocabulary), or OTLP resource processors — the agent translates “first evidence” and “next batch” into the explicit binding. Persisted investigations are also visible in the AI System workspace under Investigations.
Rules for agents
- Read
HAIEC_BASE_URL,HAIEC_API_KEY,HAIEC_AI_SYSTEM_ID, andHAIEC_SOURCE_ASSET_IDfrom server-side environment or the developer's non-public config. - Never display, commit, or log the API key. Never use
NEXT_PUBLIC_*for it. - Never send
githubToken,X-GitHub-Token,GITHUB_TOKEN, ororganizationIdto HAIEC. - Use only configured Source Asset IDs — never a raw repository URL.
- Always send an
Idempotency-Keyon run creation; poll run status at 15–30s intervals and stop on terminal failure. - Report exactly what the API returns: run ID, evaluation ID, disposition, what was established, what was not, limitations, report/agent-audit/passport/dashboard links.
- Prefer
GET .../agent-auditover the full report for “what did HAIEC prove / what is missing” questions — it carriesnarrative.established,unestablished,notAssessed,evidenceGaps, andverificationItems[].verificationNeededverbatim. - Never manufacture PASS when evidence is missing, partial, or not assessed — and never translate NOT_ASSESSED or UNKNOWN into FAIL.
- Submit evidence only on explicit user request, only through a configured binder, and only via the canonical intake routes. An ingestion receipt means EVIDENCE_INGESTED — never a closed gap; only a new Evaluation establishes change.
- Running a scan never requires code changes; remediation is a separate user decision.
Canonical flow
configured Source Asset
→ POST /api/v1/assurance/runs
→ poll GET /api/v1/assurance/runs/{runId}
→ GET links.summary → GET links.agentAudit
→ GET links.masterReport (bounded) — canonical Master Assurance Report
→ GET links.masterReport?detail=full only when deeper analysis is required
→ links.report / links.pdf remain the secondary Assurance Evidence artifacts
→ open links.dashboard in the HAIEC Dashboard
optional, explicit user request only:
GET /api/v1/evidence/binders → POST /api/ingest/* or /api/otlp/v1/*
→ attach receipt.producerRunId to a NEW run (producerId: structured-ingress)
→ compare old vs new evaluation factsTelemetry and evidence ingestion are OPTIONAL — static Assurance needs only the key, AI System, and verified Source Asset. Ready-to-use agent instructions exist per tool: Cursor, Claude Code, Devin, and a generic agent guide for everything else.
When something fails
Translate known error codes into the exact user action. Do not turn optional evidence setup into a global Assurance blocker.
| Error | Meaning | Tell the user to |
|---|---|---|
UNAUTHORIZED | API key missing, invalid, revoked, or expired. | Create a fresh Assurance Agent key at /dashboard/api-keys and update HAIEC_API_KEY. |
INSUFFICIENT_SCOPE | The key lacks the required capability scope. | Create a key with the needed purpose at /dashboard/api-keys (e.g. evidence upload requires evidence:ingest). |
AI_SYSTEM_NOT_FOUND | The AI System ID is wrong or belongs to another organization. | Pick the system from GET /api/v1/systems, or connect one at /dashboard/ai-inventory. |
SOURCE_NOT_VERIFIED | No VERIFIED repository Source Asset is bound to this AI System. | Install the HAIEC GitHub App and verify the repository under AI System → Connected Assets. |
BRANCH_REQUIRED | No evaluation branch could be proven for the source. | Pass an explicit branch, or re-verify the source so its default branch is established. |
CONSENT_REQUIRED | A private repository needs a user-bound consent record. | Grant repository consent in the HAIEC dashboard once; subsequent API runs reuse it. |
RATE_LIMITED | Per-key rate limit exceeded. | Retry after Retry-After seconds. Limits are abuse controls, not plan quotas. |
IDEMPOTENCY_CONFLICT | Same Idempotency-Key with a different payload, or creation still in progress. | Use a fresh Idempotency-Key per distinct run; retry shortly if one is in flight. |
When HAIEC is not connected — local Quick Check
## When the user asks to "run HAIEC" — decision sequence 1. FULL ASSURANCE — HAIEC MCP or API key is configured and reachable: use the normal Assurance workflow (haiec_preflight → haiec_run_assurance → poll → summary → agent audit). 2. SETUP REQUIRED — HAIEC MCP is connected but haiec_preflight reports setup incomplete: explain the exact missing steps from preflight verbatim. If a local repository is available, you may also offer a Quick Check (below) — never in place of completing setup. 3. NO HAIEC CONNECTION — no API key or MCP configured, local repository available: say exactly — "Full HAIEC Assurance is not connected for this repository. I can still run HAIEC's independent local developer-security tools for a preliminary source-security review. These results are not a HAIEC Assurance Evaluation and will not appear in the HAIEC Assurance dashboard." Offer, only with the user's approval before installing or running: - AI AppSec (npx -y ai-appsec) — deterministic static source-security analysis for AI/agent code (requires Semgrep installed separately). - MCP Tenant Isolation (npx -y mcp-tenant-isolation mcp) — only when the repository builds MCP servers or tools. ## Presenting Quick Check results Inspect the repository deeply and propose fixes, but keep three kinds of statements clearly separate: - DETERMINISTIC PACKAGE FINDING — exactly what the scanner reported (rule, file, line). Quote it; never rewrite it as a HAIEC finding. - AI REPOSITORY INTERPRETATION — your reading in this codebase's context (reachability, exploitability, affected paths). - AI RECOMMENDATION — likely remediation and what to verify. Lead with the most important findings first, name the affected files, state the package's limitations, and close with what a full HAIEC Assurance Evaluation could additionally answer (capability and action-path analysis, authority/policy evidence, runtime evidence, Guided Assurance, Agent Audit, Reports, Passport). After the check, say: "These were independent HAIEC developer-security checks performed locally. They do not create a HAIEC Assurance Evaluation and are not stored in your HAIEC Assurance dashboard. Full HAIEC Assurance adds broader capability and action-path analysis, authority and policy evidence, runtime evidence, Guided Assurance, Agent Audit, Reports and Passport." Truth locks: - AI_APPSEC_RESULT != HAIEC_ASSURANCE_EVALUATION - MCP_TENANT_ISOLATION_RESULT != HAIEC_ASSURANCE_EVALUATION - FREE_LOCAL_CHECK != FULL_HAIEC_ASSURANCE - LOCAL_PACKAGE_RESULT != HAIEC_DASHBOARD_EVIDENCE
Try these with your AI
Copy any prompt into your configured agent.
- “Check whether HAIEC is ready to evaluate this system.”
- “Run HAIEC Assurance on the connected source.”
- “Explain my HAIEC result in plain English.”
- “What did HAIEC establish?”
- “What remains unknown or not assessed?”
- “Group the open evidence questions and tell me which ones you can help resolve.”
- “What evidence is missing?”
- “Show me the highest-consequence action paths.”
- “Which capabilities are code-capable but not runtime-observed?”
- “Help me investigate the evidence gap using only the files and diagnostics I authorize.”
- “Show me the exact evidence preview, including who provided it and how it was normalized.”
- “Help me connect the evidence HAIEC says is missing.”
- “Can these logs help close any HAIEC evidence gaps?”
- “Submit these logs to HAIEC and rerun Assurance.”
- “Configure telemetry for this project, but ask before changing my files.”
- “Run the authorized runtime preflight.”
- “Compare this Evaluation with the previous one.”
- “Open the exact HAIEC report for this run.”
- “Start a HAIEC investigation.”
- “This is my first evidence.”
- “Here is the next batch — start collecting the next state.”
- “Continue my HAIEC investigation.”
- “What changed between my first evidence and the latest state?”
- “Where does the proof stop?”
Where each step happens
- /dashboard/api-keysCreate the scoped Bearer key (Assurance Agent for runs; evidence:ingest only when uploads are planned).
- /docs/github-integrationAuthorize the GitHub App and bind a repository to a verified Source Asset.
- /monitoring/iamOptional AWS IAM authority evidence (partial).
- /monitoring/sources/onboardOptional OTLP telemetry and source onboarding.
- /dashboard/settings/integrations/cloudOptional AWS account and region connections.
- /ai-inventoryProvider admin usage and cost reporting (separate credential pathway).
- /api-platformThe REST surface, when you call the API directly instead of MCP.
- /enterpriseConsultative scoping for customer-specific source adapters and operational coverage.