MCP (Model Context Protocol)
Connect your own AI agent to your DuoKey tenant's data and operations, under your own permission boundary.
What is the MCP endpoint?
The Cockpit can expose a tenant's data and operations to an AI agent over the Model Context Protocol (MCP), an open standard for connecting AI assistants to external systems. Because the endpoint speaks standard MCP, any MCP-compatible client can connect — Claude Code, Claude.ai (web), Claude Desktop, ChatGPT, and Microsoft Copilot are covered below. Once connected, the agent can be asked to look at your PQC posture, inventory your keys and vaults, review your certificate estate, or (where you choose to allow it) carry out change work such as issuing a certificate or drafting a remediation — all read and write access is scoped to a single tenant and bounded by the same permissions the connecting user or key already has in the Cockpit.
Every call is mapped onto an existing DuoKey service — the MCP layer adds authentication and capability gating, not new business logic.
Your data, your boundary
Every connection resolves to exactly one tenant. An agent connected on one tenant's key or session can never see another tenant's data.
Opt-in by capability
Nothing is exposed by default beyond what your edition grants and what an admin has explicitly switched on — see capability packs below.
Still your permissions
A capability pack being on does not widen what any individual call can do — every action is still checked against the permissions of the user who minted the key or approved the connection.
The MCP endpoint is a distinct entitlement on top of the capabilities it exposes. It is disabled by default until your edition grants it and a tenant admin turns it on from the Cockpit console.
Connecting an AI agent
There are two ways to authenticate an AI client against the endpoint, chosen based on what kind of client is connecting.
| Method | Used by | How it works |
|---|---|---|
| Per-tenant API key | Claude Code, scripted / CI use | A long-lived key is minted once in the Cockpit console and supplied as a bearer credential on every request. Intended for command-line and automated clients that cannot open a browser. |
| OAuth sign-in | Claude.ai (web), Claude Desktop, ChatGPT | The client is pointed at the endpoint URL and redirects the user through the normal Cockpit sign-in (so MFA / SSO / passkeys are enforced as usual), followed by a one-time consent screen. Intended for interactive clients that can complete a browser-based approval. |
Mint an API key (Claude Code / scripted clients)
From the MCP page in the Cockpit, create a key and give it a name. The key value is shown exactly once — copy it immediately, it cannot be recovered afterwards. Add it to the client with a bearer Authorization header, for example:
claude mcp add --transport http duokey <endpoint-url> --header "Authorization: Bearer <mcp-key>"Or connect an interactive client (Claude.ai / Claude Desktop / ChatGPT)
In the client's connector settings, add a custom connector pointing at the tenant's MCP endpoint URL (shown on the MCP page in the Cockpit). The client redirects you to sign in to the Cockpit as usual, then shows a consent screen. In ChatGPT this connector option lives behind Developer mode (Settings → Connectors, or the composer's + → More → Developer mode on a Plus, Pro, Team, Enterprise, or Edu plan — not available on the Free plan; on a Team/Enterprise workspace an admin must first turn Developer mode on for the workspace).
Review and approve the consent screen
The consent screen names the application requesting access, shows where it will redirect once approved, and summarizes in plain language what approving lets it do. Approve to complete the connection, or deny to cancel it.
The agent is now connected
From this point the agent can call whichever tools its capability packs and your own permissions allow — nothing more.
An interactive (OAuth) connection is renewed automatically by the client in the background for as long as it stays in use; left completely idle, it eventually needs to be re-approved. An API key does not expire on its own — it stays valid until it is revoked (or an optional expiry you set at creation time is reached).
Microsoft Copilot (Bring Your Own MCP)
Microsoft Copilot doesn't take a connector URL directly from end-user settings the way Claude or ChatGPT do. Instead, a tenant admin registers the DuoKey endpoint once with Microsoft Agent 365, through its Bring Your Own (BYO) MCP server feature; once approved, it becomes available as a tool inside Copilot Studio agents (the currently supported surface — Visual Studio Code, Claude Code, and GitHub Copilot CLI can also consume it this way, but a plain Microsoft 365 Copilot chat cannot yet).
BYO MCP server is a Microsoft preview feature as of this writing, gated behind its own supplemental terms and subject to change. Treat this section as directional, and confirm current behavior against Microsoft's own documentation before relying on it.
Mint a DuoKey API key
Same as for Claude Code: create a per-tenant API key from the MCP page in the Cockpit.
Register the endpoint with the Agent 365 CLI
A developer or admin with the Agent 365 CLI installed registers the DuoKey endpoint as an external MCP server, using API-key authentication in a request header:
a365 develop-mcp register-external-mcp-server \
--server-name "DuoKey Cockpit" \
--server-url "<endpoint-url>" \
--description "DuoKey Cockpit MCP endpoint" \
--auth-type APIKey \
--api-key-location Header \
--api-key-name Authorization \
--tools "list_keys,get_qrs_score,get_vulnerable_assets,..."Agent 365 enforces its own limits on tool name and description length; the CLI reports which of your enabled tools, if any, need shortening before they'll register.
An IT admin reviews and approves the request
The registration shows up in the Microsoft 365 admin center under Agents → Tools → Requests, where an AI admin or Global admin reviews the declared tools and either approves or rejects the server. Approval also grants the Microsoft Entra permissions the connection needs.
Use it from a Copilot Studio agent
In Copilot Studio, add MCP Server as a tool on the agent and select the approved DuoKey server from the registry. The first invocation prompts the end user to complete a one-time connection — entering the DuoKey API key they were given — after which the agent can call the enabled tools.
Capability packs: two gates, not one
What an agent can actually do is organized into named capability packs — PQC, KMS, vaults, PKI, and so on. Each pack sits behind two independent gates, and both must be open for the pack to do anything:
| Gate | Decided by | Meaning |
|---|---|---|
| Available | Your edition | The ceiling. Your edition either grants a pack or it doesn't, and most packs also require their underlying capability to already be enabled on the tenant (for example, the KMS pack additionally needs key management itself to be on). A tenant can never exceed this ceiling. |
| Enabled | A tenant admin | Within that ceiling, an admin switches each pack on or off for AI agents from the MCP page. Read-only packs are on by default the moment they become available; every write-capable pack starts off and must be explicitly turned on. |
Separating "available" from "enabled" means an edition upgrade never silently turns on new AI-agent capability — a tenant admin always has to make the deliberate second choice to switch a pack on, especially any pack that lets the agent make changes.
Read packs cover read-only lookups and posture questions; write packs let the agent take actions such as creating keys, issuing certificates, or deploying to network equipment. Every write pack remains bounded by the connecting user's own permissions in that area — enabling the pack only removes the MCP-level gate, not the underlying permission check.
| Pack | Tier | Default | What it lets an agent do |
|---|---|---|---|
| PQC Readiness | Read | On | List scans, read the Quantum Readiness Score and CBOM, list vulnerable assets, and read remediation status. |
| KMS / Keys | Read | On | List the tenant's keys and read a key's metadata. |
| Vaults / HSM | Read | On | List vaults and the keys held in them. |
| PKI / Certificates | Read | On | List certificate authorities, certificates, expiring and discovered certificates, and issuers. |
| Apps / Integrations | Read | On | List the tenant's configured applications and integrations. |
| DKE | Read | On | List DKE services configured for the tenant. |
| Audit / Activity | Read | On | Query the tenant activity log. |
| Crypto Agility Plane | Read | On | List crypto intents, resolve an intent against the active policy, simulate a posture change, and diff two policy versions. |
| PQC Migration | Write | Off | Create post-quantum keys, retire or revoke classical keys, and build migration plans. No encrypt / decrypt / sign access. |
| PQC Autopilot | Write | Off | Draft a remediation for a vulnerable asset on a new branch, verify it, and open a pull request for a human to merge. Never writes to production and never auto-merges. |
| PKI Lifecycle | Write | Off | Generate CAs, issue and sign certificates, renew, and revoke. Private keys are never returned. |
| PKI Deploy | Write | Off | Push managed certificates to external network targets (such as load balancers and firewalls) and roll deployments back. This is the one pack that reaches outside the Cockpit to live network equipment. |
| ServiceNow CMDB | Write | Off | Read certificate configuration items from a connected ServiceNow instance, sync certificates into it, and raise expiry incidents. Off by default like every write pack; the write actions additionally require the connecting user's own ServiceNow sync permission. |
Unlike the other packs, PKI Deploy mutates equipment outside the Cockpit. Treat it with the same caution as any other automation with production network access, and keep it off unless you specifically intend an agent to push certificate changes.
Anatomy of a tool call
Every single tool invocation — whether a read like listing keys or a write like issuing a certificate — goes through the same five steps:
The capability-pack gate is checked again at dispatch time, not only when the tool list is built — a pack disabled mid-session stops working on the very next call.
A mocked example session
The prompt, tool calls, and JSON below are invented for this example — they are not a real tenant's data. They show the shape of a round trip, not actual DuoKey output.
The user asks a question
What's our quantum readiness posture for shop.example.com, and are there any critical PQC findings we should act on?The agent calls get_qrs_score
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_qrs_score",
"arguments": { "domain": "shop.example.com" }
}
}{
"domain": "shop.example.com",
"scan_id": "5f1e2c3a-7b9d-4a11-9e2f-8a6d0c1b7e44",
"total": 62,
"band": "Moderate",
"signals": [
{ "name": "algorithm_resilience", "value": 55, "weight": 35, "justification": "RSA-2048 and ECDHE-P256 still in active use on 2 of 6 hosts." },
{ "name": "crypto_agility", "value": 70, "weight": 20, "justification": "TLS config supports cipher-suite rotation without app changes." },
{ "name": "harvest_exposure", "value": 48, "weight": 25, "justification": "Long-lived session data observed over classical key exchange." },
{ "name": "migration_posture", "value": 75, "weight": 20, "justification": "PQC migration plan exists and is partially executed." }
],
"subdomains": [],
"disclaimer": "The QRS is a proprietary, observable-posture methodology — not a security audit or regulatory attestation."
}The agent calls get_vulnerable_assets, scoped to Critical
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_vulnerable_assets",
"arguments": { "scan_id": "5f1e2c3a-7b9d-4a11-9e2f-8a6d0c1b7e44", "severity": "Critical" }
}
}{
"assets": [
{
"id": "a-central-checkout-tls",
"finding_type": "TLS certificate — RSA-2048 key exchange",
"source": "tls_scan",
"location": "checkout.shop.example.com:443",
"severity": "Critical",
"quantum_vulnerable": true,
"reasons": ["Key exchange relies on RSA-2048, broken by a cryptographically relevant quantum computer."],
"recommendations": ["Migrate to an ML-KEM hybrid key-exchange profile ahead of certificate renewal."]
}
],
"limit": 500,
"offset": 0,
"returned": 1,
"has_more": false
}The agent answers in plain language
shop.example.com scores 62/100 (Moderate). One Critical finding: checkout.shop.example.com's TLS certificate still negotiates RSA-2048 key exchange, which a quantum-capable attacker could break — recommend moving it to an ML-KEM hybrid profile at next renewal. No other Critical findings on this scan.Usage limits
Two numeric limits, both set by your edition, bound how much an agent can do against a tenant:
| Limit | Applies to | Convention |
|---|---|---|
| Maximum active API keys | Checked when minting a new key | -1 unlimited · 0 none · n maximum active keys at once |
| Maximum tool calls per day | Checked on every request, on a rolling 24-hour window | -1 unlimited · 0 none · n maximum calls per rolling 24h |
An agent can send several tool calls in a single request. Every call in that request counts against the rolling daily limit — a batch is never a way around the quota. Once the limit is reached, further calls are refused until the 24-hour window rolls forward.
Managing MCP from the Cockpit console
Check status
The MCP page shows a live health indicator, the endpoint URL, the protocol version in use, how many keys and OAuth sessions are currently active, and how many tool calls have run in the last 24 hours.
Mint or revoke API keys
Create a new key for each client that needs one (a distinct key per client makes it easy to revoke one without affecting the others). Revoking a key takes effect immediately.
Review or end OAuth sessions
See how many interactive (OAuth) sessions are currently active. "Disconnect all AI clients" revokes every one of them at once — access tokens already issued stop working immediately rather than waiting out their normal expiry.
Turn capability packs on or off
Toggle each pack within what your edition makes available. A pack your edition doesn't grant is shown but cannot be switched on.
Because usage and revocation are tracked per key, minting a separate key for each client (rather than sharing one key across several tools) keeps a compromised or retired client's access easy to cut off without disturbing anything else connected.
Permissions and entitlements
MCP has its own permission subtree, separate from the domain permissions (PQC, keys, PKI, and so on) that still govern what any individual tool call may actually do:
| Permission | Governs |
|---|---|
| View MCP status & keys | See the status panel, the list of API keys (never the secret values) and the capability-pack states |
| Manage MCP | Mint and revoke API keys, disconnect OAuth sessions, and turn capability packs on or off |
Whether the MCP endpoint and each capability pack exist at all for your tenant is decided by your edition's feature entitlements; whether this user may manage them is decided by permissions. A call must pass both, and every tool call an agent makes is additionally bounded by the permissions of the user who minted the key or approved the OAuth connection. See Features and Access Policies.