Duo

MCP server for the Cisco Duo Admin API — Duo's multi-factor authentication and zero-trust access platform. Built to cover MFA synchronization, user pre-enrollment, and enrollment validation (the capabilities this task specifically requested), and — per an explicit follow-up scope decision — the full Admin API beyond that.

Overview

• Stateless HTTP service. No credentials are ever persisted — each request supplies its own integration key/secret key/API host via headers, used only for the lifetime of that single request.
• Supports concurrent requests; per-request credential isolation is done via Python contextvars, not a global/shared client instance.
• Entry points: POST /mcp (MCP protocol) and GET /health (health check).
• Default port: 8080 (configurable via MCP_HTTP_PORT).

Scope

160 tools across 20 categories (Users, Groups, Phones, Tokens, WebAuthn Credentials, Desktop Authenticators, Bypass Codes, Integrations, Policies, Endpoints, Registered Devices, Passport, Administrators, Administrative Units, Logs, Trust Monitor, Settings, Custom Branding, Account Info, Bulk Operations).

No MSPbots-existing integration to anchor scope against — Duo was not previously configured in MSPbots' integration platform, and the ClickUp task itself only asked for MFA sync / pre-enrollment / enrollment validation. Per explicit follow-up decision, this build covers the entire public Admin API, matching the pattern used for other large-API vendors in this program.

No official Duo MCP exists — searched GitHub (duo-mcp, "duosecurity" mcp) and both wyre-technology/MSPbotsAI orgs before building; the only existing "Duo + MCP" material is Duo SSO for MCP, which is the reverse relationship (Duo as an identity provider protecting MCP servers), not a Duo Admin API MCP server.

Source data was extracted from Duo's own official Postman collection (https://github.com/duosecurity/duo_postman_collection, duo-admin-api folder — cloned locally and parsed), cross-referenced against the live duo.com/docs/adminapi documentation for required/optional parameter flags.

Authentication

Duo Admin API auth is not a simple bearer token — every request is individually signed with HMAC-SHA512 (Duo's "sig_version 5") using an Integration Key (ikey) and Secret Key (skey). This server implements that signing logic itself (ported line-for-line from Duo's own reference Python client and verified byte-for-byte identical against that reference implementation for both GET-style query-signed requests and POST-style JSON-body-signed requests, including special-character percent-encoding) — callers only need to supply the raw ikey/skey/host per request; this server computes the canonical string, HMAC, and Authorization: Basic header on every call.

Per Duo's own signing convention: GET/DELETE requests sign and send params as a url-encoded query string; POST/PUT/PATCH requests sign and send params as a single JSON object request body. Tools in this server don't need to know which — the client picks the correct transport based on the HTTP method automatically, exactly matching the reference implementation's behavior.

HEADER 授权参数说明

Missing any header returns 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-Duo-Ikey, X-Duo-Skey, and X-Duo-Api-Host headers",
  "required_headers": ["X-Duo-Ikey", "X-Duo-Skey", "X-Duo-Api-Host"],
  "optional_headers": []
}

Environment Variables

MCP Endpoint

• POST /mcp — MCP protocol (streamable HTTP transport)
• GET /health — health check, returns {"status": "ok", "service": "duo-mcp", "transport": "http"}

Tool List

Tool names are duo_<category>_<operation>, derived from each operation's name in Duo's official Postman collection. body parameters (for endpoints whose payload is a nested/complex JSON object rather than flat scalar fields, e.g. bulk operations, SSO integration config, policy sections) are accepted as a generic dict — the docstring lists the top-level keys from Duo's own example, and the full schema is in the linked API reference.

The 3 capabilities this task specifically named map to these tools:

• MFA synchronization: duo_users_retrieve_users, duo_users_synchronize_user_from_directory
• User pre-enrollment: duo_users_create_user, duo_users_enroll_user
• Enrollment validation: duo_users_send_verification_push + duo_users_retrieve_verification_push_response

测试示例

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Duo-Ikey: <your-integration-key>" \
  -H "X-Duo-Skey: <your-secret-key>" \
  -H "X-Duo-Api-Host: api-xxxxxxxx.duosecurity.com" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "duo_users_retrieve_users",
      "arguments": {"limit": "5"}
    }
  }'

Signing correctness verified independently of any live account: this server's HMAC-SHA512 request-signing implementation was directly compared, side-by-side in the same Python process, against Duo's own official reference client (duo_client_python) — the canonical string, the full Authorization: Basic header, and percent-encoding of special characters were all confirmed byte-for-byte identical for both a GET (query-signed) and a POST (JSON-body-signed) scenario. Structural checks were also completed: MCP handshake, tools/list returning all 160 registered tools, and 401 credential-gating with placeholder header values.

Live self-test against a real Duo account has not yet been performed — no test ikey/skey/host was provided with this task (unlike prior vendor tasks). See Known Gaps.

API Reference

• Admin API docs: https://duo.com/docs/adminapi
• Official Postman collection: https://github.com/duosecurity/duo_postman_collection
• Reference Python client (signing algorithm source): https://github.com/duosecurity/duo_client_python

Known Gaps

• Full API coverage was an explicit user decision after confirming no official/community Duo Admin API MCP exists and no MSPbots-existing integration could anchor a narrower scope. Every Create/Modify/ Delete/Bulk tool mutates real Duo account configuration (users, groups, phones, tokens, integrations, policies, administrators, custom branding, etc.) — treat these as destructive/irreversible and confirm with a human before invoking, especially anything under administrators (could lock out real admin accounts) or integrations/policies (could break production SSO/access policies).
• body parameters are untyped (dict) for the ~20 endpoints with nested/complex JSON payloads (bulk operations, SSO integration config, policy sections, shared-device-auth config) — each tool's docstring lists the top-level keys from Duo's own example payload; the full schema is in the linked API reference.
• Live functional self-test not yet performed — no real Duo Admin API credentials (ikey/skey/host) were provided with this task. The signing implementation itself has been independently verified against Duo's own reference client (see above), which gives strong confidence the auth layer is correct, but no tool has been exercised against a live account with real data yet.
• Duo's own official Postman collection has two small authoring inconsistencies, both worked around here: (1) some path placeholders use [bracket] notation instead of Postman's {{double-brace}} variables — both styles are recognized; (2) two operations (Create Integrations (legacy), Modify Integration) list the same query parameter twice under one operation — deduplicated, keeping the first occurrence. One operation (Remove Draft Custom Branding User by ID) has a malformed request object with no url at all in the source collection and was skipped entirely (160 usable tools + this 1 skipped = the source collection's nominal 161 total).