> ## Documentation Index > Fetch the complete documentation index at: https://docs.certgov.app/llms.txt > Use this file to discover all available pages before exploring further. # MCP / AI Agents > Connect AI assistants to CertForge using the Model Context Protocol (MCP). Query certificates, manage governance, and automate certificate delivery in plain language. ## Overview CertForge implements the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), an open standard that lets AI assistants call structured tools over HTTP. Once connected, you can manage your certificate environment in plain language — no API client, no scripting. ``` "Check if fun.example.com has a trust profile and CA configured" "Walk me through setting up auto-issuance for my nginx server" "Create a trust profile for *.internal.example.com using Let's Encrypt" ``` Every tool call is logged with latency, status, and the key that made the request. The **MCP / AI Agents** dashboard (Settings → MCP / AI Agents) shows usage analytics and unsolved queries — requests the AI couldn't fulfill because CertForge hasn't exposed that capability yet. *** ## Prerequisites * A CertForge API key with the **`mcp`** scope (Settings → API Keys → Add Key) * An MCP-compatible AI client (see [Compatible Clients](#compatible-clients)) *** ## Endpoint ``` POST https://app.certgov.app/mcp Authorization: Bearer Content-Type: application/json ``` Self-hosted: replace `app.certgov.app` with your own hostname. Transport: **Streamable HTTP** (MCP 2024-11-05). Single POST endpoint; synchronous JSON responses. *** ## Available Tools ### Certificates & Audit | Tool | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `list_certificates` | List issued certificates. Filter by domain, status (`active` / `revoked` / `expired`), and limit. | | `get_certificate` | Full details for a certificate by ID — serial, CA, expiry, auto-renew, revocation, and security rating (A–F grade with factor breakdown). | | `list_audit_events` | Recent audit log events. Filter by event type prefix, actor email, and time window. | | `get_org_summary` | Org posture snapshot — active, expired, expiring-in-30-days, and revoked cert counts. | ### Governance — Query | Tool | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_trust_profiles` | List all Trust Profiles. Optional `domain` filter returns only profiles covering that domain. | | `get_trust_profile` | Detailed view of a Trust Profile — domains, CA, GL code, approval policy, SANs. Lookup by `id` or `domain`. | | `list_applications` | List registered applications. Filter by `environment` or `owner` email. | | `get_application` | Full details for an application by `id` or `name`. | | `list_issuance_profiles` | List all Issuance Profiles — CA, key algorithm, validity, wildcard settings. | | `list_gl_codes` | List all GL codes — ID, label, code string, owner, annual budget. | | `list_connectors` | List connectors by `kind`: `ca` (Certificate Authorities), `device`, or `app`. | | `list_dns_accounts` | List DNS accounts configured for ACME DNS-01 validation — provider, zone IDs, credential presence, config issues (e.g. missing `zone_id`), and which issuance profiles use each account. | ### Diagnostics | Tool | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `check_domain` | Comprehensive coverage report for a domain — Trust Profile, Issuance Profile, Application, Connector, and governance checks in one call. | | `check_dns` | DNS resolution from the CertForge server — A, AAAA, CNAME, TXT, MX records. Confirms the domain is reachable before cert issuance. | | `list_dns_accounts` | List DNS accounts configured for ACME DNS-01 validation. Shows provider, zone IDs, config health warnings (e.g. missing `zone_id` causing Cloudflare zone-lookup failures), and which issuance profiles depend on each account. | ### Setup Guidance | Tool | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | `plan_setup` | Personalized step-by-step nginx auto-issuance plan. Checks current state and marks each step done or required. Links to docs for each step. | ### Action Tools — Create (two-step) Action tools require explicit confirmation before writing anything. See [Two-Step Confirmation](#two-step-confirmation) below. | Tool | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------ | | `create_trust_profile` | Create a new Trust Profile — domains, CA, approval policy, GL code, SANs. | | `create_application` | Create a new Application record — hostname, environment, owners, preferred Trust Profile. | | `create_app_connector` | Create an App Connector — ties a domain to the connector agent and defines cert delivery paths and reload command. | | `create_gl_code` | Create a new GL code for cost attribution — label, code string, owner email, annual budget. | ### Feedback | Tool | Description | | --------------------------- | --------------------------------------------------------------------------------------------------------- | | `list_mcp_analytics` | Tool usage analytics — call counts, error rates, avg latency per tool. | | `report_missing_capability` | Called automatically by the AI when it can't fulfill a request. Logged to the Unsolved Queries dashboard. | *** ## Example: Diagnosing an ACME Issuance Failure When a certificate fails to issue, the agent can trace the problem end-to-end: ``` "Why did cert issuance fail for secure.example.com?" ``` The agent calls: 1. `check_domain(domain="secure.example.com")` — finds the Trust Profile and Issuance Profile 2. `list_dns_accounts()` — inspects the Cloudflare DNS account referenced by that profile The DNS account response flags the issue immediately: ```json theme={null} { "provider": "cloudflare", "zone_id": null, "config_issues": [ "zone_id is not set — Cloudflare will attempt auto-discovery by zone name. If the domain is not in your Cloudflare account this will fail with 'could not find zone'. Set zone_id to bypass the lookup." ], "used_by_issuance_profiles": ["letsencrypt-90d"] } ``` **Fix:** Settings → DNS Accounts → edit the Cloudflare account → add the Zone ID from your Cloudflare dashboard (domain → right sidebar → Zone ID). *** ## Example: Certificate Security Rating Every certificate issued by CertForge carries a security grade. The `get_certificate` tool includes it automatically: ```json theme={null} "security_rating": { "grade": "A", "score": 93, "key_algorithm": "ECDSA P-256", "signature_algorithm": "SHA-256", "validity_days": 90, "validity_pct": 71, "auto_renew": "Enabled" } ``` Grades are computed from five factors: key algorithm (35 pts), signature algorithm (20 pts), validity period (20 pts), validity remaining (15 pts), and auto-renew (10 pts). SHA-1 or MD5 forces grade F regardless of other factors. The rating is also shown as a visual scorecard on the certificate detail page in the CertForge UI. *** ## Two-Step Confirmation All action tools (`create_*`) use a mandatory two-step flow. **Passing `dry_run=false` alone is not enough** — the tool also requires `confirmed=true`. This is enforced in code, not just instructions. ### Step 1 — Preview (default) Call the tool with any arguments. A preview is always returned first: ```json theme={null} { "preview": { "name": "nginx prod", "domains": ["fun.example.com"], "default_issuance_profile_id": "letsencrypt-90d" }, "note": "SHOW THIS TO THE USER. After they confirm, call again with dry_run=false AND confirmed=true to create." } ``` ### Step 2 — Execute After the user confirms, call again with both `dry_run: false` and `confirmed: true`: ```json theme={null} { "name": "nginx prod", "domains": ["fun.example.com"], "default_issuance_profile_id": "letsencrypt-90d", "dry_run": false, "confirmed": true } ``` If either flag is missing, the preview is returned again — it cannot be bypassed. *** ## Example: End-to-End nginx Setup The `plan_setup` tool generates a personalized checklist from your current state: ``` "I have an nginx server at fun.example.com and want auto-renewal" ``` The AI calls `plan_setup(domain="fun.example.com", goal="nginx_auto_issuance")` and gets back a step-by-step plan: 1. **Create an Issuance Profile** (if none exists) → links to the [Issuance Profiles guide](/guides/issuance-profiles) 2. **Create a Trust Profile** for `fun.example.com` → links to [Trust Profiles](/guides/trust-profiles) 3. **Create an Application** record → links to [Applications](/guides/applications) 4. **Install the connector agent** on the nginx host → links to [Connector Agent](/guides/connector-agent) 5. **Create an App Connector** record → links to [App Connector](/guides/app-connector) 6. **Verify end-to-end** with `check_domain` and `check_dns` Steps already completed are marked `done`. The AI then walks through each `required` step using the two-step create flow — previewing each change before creating it. *** ## Setup: Claude Desktop Edit `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json theme={null} { "mcpServers": { "certforge": { "command": "npx", "args": ["-y", "mcp-remote", "https://app.certgov.app/mcp"], "env": { "MCP_HEADER_AUTHORIZATION": "Bearer " } } } } ``` Restart Claude Desktop. CertForge tools are available in every conversation. Edit `%APPDATA%\Claude\claude_desktop_config.json`: ```json theme={null} { "mcpServers": { "certforge": { "command": "npx", "args": ["-y", "mcp-remote", "https://app.certgov.app/mcp"], "env": { "MCP_HEADER_AUTHORIZATION": "Bearer " } } } } ``` Restart Claude Desktop. *** ## Setup: Claude Code (CLI) Claude Code runs on Linux, Mac, and Windows. Add CertForge as a server: ```bash theme={null} claude mcp add certforge \ --transport http \ https://app.certgov.app/mcp \ --header "Authorization: Bearer " ``` Verify: ```bash theme={null} claude mcp list ``` Start a new `claude` session — MCP tools initialize at session start. *** ## Setup: Cursor Add to `~/.cursor/mcp.json` (create if it doesn't exist): ```json theme={null} { "mcpServers": { "certforge": { "url": "https://app.certgov.app/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Restart Cursor. CertForge tools appear in the agent panel. *** ## Setup: Zed Add to `~/.config/zed/settings.json`: ```json theme={null} { "context_servers": { "certforge": { "command": { "path": "npx", "args": ["-y", "mcp-remote", "https://app.certgov.app/mcp"] }, "settings": {} } } } ``` *** ## Setup: OpenAI-compatible clients (Grok, GPT-4o, etc.) Clients that use OpenAI function-calling (xAI Grok, OpenAI Assistants, etc.) don't support the MCP transport natively. Use `mcp-bridge` to proxy: ```bash theme={null} npx -y mcp-bridge \ --mcp-url https://app.certgov.app/mcp \ --mcp-header "Authorization: Bearer " \ --port 8080 ``` Then configure your client to call `http://localhost:8080` for tools. *** ## Compatible Clients | Client | Platform | MCP support | Notes | | ------------------ | ------------------- | ------------- | ----------------------------------- | | **Claude Desktop** | Mac, Windows | ✅ Native | Streamable HTTP via `mcp-remote` | | **Claude Code** | Linux, Mac, Windows | ✅ Native | `claude mcp add --transport http` | | **Cursor** | Linux, Mac, Windows | ✅ Native | JSON config in `~/.cursor/mcp.json` | | **Zed** | Linux, Mac | ✅ Native | `context_servers` in settings | | **Continue** | VS Code / JetBrains | ✅ Native | MCP tools in `config.json` | | **Windsurf** | Mac, Windows | ✅ Native | Cascade agent panel | | **Grok (xAI)** | Web | ⚠️ Via bridge | Use `mcp-bridge` today | | **GPT-4o** | API | ⚠️ Via bridge | OpenAI function-calling format | *** ## Analytics & Unsolved Queries Every tool call is recorded in the **MCP / AI Agents** dashboard (Settings → MCP / AI Agents): * **Tool Usage** — which tools are called, how often, error rates, and average latency * **Recent Calls** — last 50 invocations with status, latency, arguments, and the key that made the call * **Unsolved Queries** — requests the AI logged via `report_missing_capability` when no tool existed for what the user asked The Unsolved Queries list is a live product backlog. The most common gaps drive which MCP tools CertForge adds next. *** ## Testing the Connection ```bash theme={null} # List available tools curl -s -X POST https://app.certgov.app/mcp \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq . # Run a diagnostic curl -s -X POST https://app.certgov.app/mcp \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"check_domain","arguments":{"domain":"example.com"}}}' | jq . # Get org summary curl -s -X POST https://app.certgov.app/mcp \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_org_summary","arguments":{}}}' | jq . ```