← Back to Docs Home

MCP Server (@heossihq/qnsi-mcp)

QNSI ships an official Model Context Protocol server for AI assistants. It exposes tenant-scoped tools for KMS, vault, audit, crypto posture, search, billing, and platform health using the same billing-backed entitlement model as the rest of the platform.

MCP Server (@heossihq/qnsi-mcp)

QNSI ships an official Model Context Protocol server for AI assistants. It exposes tenant-scoped tools for KMS, vault, audit, crypto posture, search, billing, and platform health using the same billing-backed entitlement model as the rest of the platform.

The MCP server is not just a convenience wrapper. It is one of the supported consumption surfaces for moving agentic workflows onto QNSI during migration and steady-state operations.

Package

  • npm package: @heossihq/qnsi-mcp
  • binary: qnsi-mcp
  • latest published npm version: 0.4.0 (28 tools, including legacy-compatible names preserved by that release)
  • runtime: Node.js >= 26.13.0

Supported deployment modes

1. Local stdio server

Use the installed binary with Kiro, Claude Desktop, VS Code, or another MCP-compatible client.

Prefer an editor install? The QNSI extension is published on the VS Code Marketplace as Heossi.qnsi.

pnpm add --global @heossihq/qnsi-mcp@0.4.0
export QNSI_API_KEY="YOUR_API_KEY"
export QNSI_PLATFORM_URL="https://api.qnsi.heossi.com"
qnsi-mcp

Configure qnsi-mcp in Kiro at ~/.kiro/settings/mcp.json, in Claude Desktop's mcpServers configuration, or in VS Code at .vscode/mcp.json. Keep real API keys out of committed workspace files.

Required environment variables:

  • QNSI_API_KEY

Optional environment variables:

  • QNSI_PLATFORM_URL Default: https://api.qnsi.heossi.com

2. Hosted Streamable HTTP endpoint

QNSI Cloud also exposes the MCP server over HTTP:

https://cloud.qnsi.heossi.com/api/mcp

Use this when the MCP client supports remote HTTP transport.

Tool surface

The latest published npm release, 0.4.0, exposes 28 tenant-scoped tools: 27 qnsp_ compatibility names and qnsp_api_request. These legacy tool identifiers remain documented because existing clients consume that published version; they are migration evidence, not active QNSP branding.

The repository source is 0.4.1 and is not published to npm. It replaces the legacy passthrough identifier with qnsi_api_request and registers 30 tools, adding qnsi_list_operations and qnsi_call_operation for manifest operation discovery and execution. The catalog describes 880 declarations, not live availability or complete payload schemas. Publication and production acceptance of these source additions are NOT VERIFIED. The npm install command above intentionally stays on 0.4.0 until a 0.4.1 release is published and independently verified.

Tool Area Description Minimum tier
qnsp_kms_generate_key KMS Generate a PQC keypair from QNSI's 90-algorithm policy catalog. Dev
qnsp_kms_list_keys KMS List keys in the current tenant. Dev
qnsp_kms_get_key KMS Retrieve a key's public metadata. Dev
qnsp_kms_rotate_key KMS Rotate a key; previous version retained for verification. Dev
qnsp_kms_hspk_seal KMS / HSPK Generate an ML-DSA-44/65/87 keypair and seal its private key under a qualified PKCS#11 HSM RSA-OAEP custody key. Enterprise
qnsp_kms_hspk_sign KMS / HSPK Unseal transiently through the HSM and sign with ML-DSA in QNSI software outside the module. Enterprise
qnsp_vault_create_secret Vault Store a secret under PQC envelope encryption. Pro
qnsp_vault_get_secret Vault Retrieve a vault secret. Pro
qnsp_vault_list_secrets Vault List secrets in the tenant. Pro
qnsp_crypto_scan Crypto posture Run configured discovery connectors and return the resulting discovery runs; accepts no input. Dev
qnsp_crypto_inventory Crypto posture List recent inventory jobs and results. Dev
qnsp_crypto_readiness Crypto posture Return the tenant's PQC-readiness scorecard. Dev
qnsp_audit_query Audit Query the immutable, hash-chained audit log. Dev
qnsp_search_query Search Run a searchable symmetric-encryption (SSE-X) query. Business
qnsp_tenant_info Tenant Show current tenant configuration. Dev
qnsp_billing_status Billing Show tier, limits, and upgrade URL. Any
qnsp_platform_health Platform Show platform liveness and regional posture. Any
qnsp_storage_list_buckets Storage List encrypted storage buckets in the tenant. Pro
qnsp_storage_list_objects Storage List objects in an encrypted bucket. Pro
qnsp_storage_put_object Storage Store an object (base64) under PQC envelope encryption. Pro
qnsp_storage_get_object Storage Fetch an object (decrypted, base64) from a bucket. Pro
qnsp_search_list_indexes Search List encrypted search indexes. Business
qnsp_search_vector_query Search Vector similarity query against an encrypted index. Business
qnsp_access_list_roles Access List access-control roles in the tenant. Business
qnsp_billing_entitlements Billing Resolved entitlements (tier, limits, enabled features). Any
qnsp_billing_list_invoices Billing List the tenant's invoices. Any
qnsp_conformance_stats Conformance L0-L3 conformance posture against pinned NIST ACVP vectors. Dev
qnsp_api_request Platform Legacy full-surface passthrough in published 0.4.0; retained for existing MCP clients. Any

If the tenant's plan does not include the feature the tool needs, the call returns a structured "upgrade required" message with a deep link to https://cloud.qnsi.heossi.com/billing - the same billing gate that protects the portal and SDKs. The edge-gateway enforces entitlements server-side as well, so the client-side check is a UX optimization and not the security boundary.

Where MCP fits in the customer journey

The migration journey is:

Connect → Discover → Analyze → Govern → Migrate → Validate → Operate

The MCP server primarily sits in Migrate, Validate, and Operate:

  • agents can consume QNSI trust services directly through MCP tools
  • migration workflows can inspect crypto posture and inventory from agent frameworks
  • post-cutover operations can query audit, health, readiness, and governed trust services through one assistant-facing surface

The MCP server does not replace discovery connectors or host agents. It complements them by giving AI assistants a governed interface into the same tenant-scoped QNSI platform.

Authentication and entitlements

The MCP server activates against QNSI using your API key before serving tool calls.

During activation it resolves:

  • tenant identity
  • billing tier
  • entitlements
  • effective limits

That means tool availability follows billing as the source of truth. For example, search tools remain tier-gated the same way they are in the portal and SDKs.

Recommended credentials:

  • Tenant API key for assistant or workload automation
  • User PAT for local human-operated testing and debugging

For shared or durable enterprise automation, prefer a service-account-backed or tenant-owned machine identity instead of a personal token.

Example MCP client configuration

Local stdio

{
	"mcpServers": {
		"qnsi": {
			"command": "qnsi-mcp",
			"env": {
				"QNSI_API_KEY": "qnsi_pqc_api_...",
				"QNSI_PLATFORM_URL": "https://api.qnsi.heossi.com"
			}
		}
	}
}

Hosted HTTP

Use the hosted endpoint if your client supports remote MCP transports:

https://cloud.qnsi.heossi.com/api/mcp

Authentication is still tenant-scoped and must use a valid QNSI API key or session-backed MCP auth flow, depending on the client integration.

Operational notes

  • The MCP server sends canonical tenant headers to the platform.
  • Tool behavior is aligned with the cloud-hosted /api/mcp route.
  • Search and other premium capabilities remain billing-gated.
  • qnsp_crypto_scan invokes configured discovery connectors and accepts no scope input.

Transport boundary

The local and hosted MCP surfaces use QNSI's public HTTPS endpoints. Native-only or hybrid-PQC negotiation at the public AWS ALB boundary is NOT VERIFIED. MCP availability and PQC operation semantics do not prove end-to-end PQC transport.

Validation

Build and test the MCP package locally:

pnpm --filter @heossihq/qnsi-mcp build
pnpm --filter @heossihq/qnsi-mcp test

Related docs