MCP / AI Agents - CertForge

Overview

CertForge implements the Model Context Protocol (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)

Endpoint

POST https://app.certgov.app/mcp
Authorization: Bearer <your-api-key>
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 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:

check_domain(domain="secure.example.com") — finds the Trust Profile and Issuance Profile
list_dns_accounts() — inspects the Cloudflare DNS account referenced by that profile

The DNS account response flags the issue immediately:

{
  "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:

"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:

{
  "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:

{
  "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:

Create an Issuance Profile (if none exists) → links to the Issuance Profiles guide
Create a Trust Profile for fun.example.com → links to Trust Profiles
Create an Application record → links to Applications
Install the connector agent on the nginx host → links to Connector Agent
Create an App Connector record → links to App Connector
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

Mac
Windows

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "certforge": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.certgov.app/mcp"],
      "env": {
        "MCP_HEADER_AUTHORIZATION": "Bearer <your-api-key>"
      }
    }
  }
}

Restart Claude Desktop. CertForge tools are available in every conversation.

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "certforge": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.certgov.app/mcp"],
      "env": {
        "MCP_HEADER_AUTHORIZATION": "Bearer <your-api-key>"
      }
    }
  }
}

Restart Claude Desktop.

Setup: Claude Code (CLI)

Claude Code runs on Linux, Mac, and Windows. Add CertForge as a server:

claude mcp add certforge \
  --transport http \
  https://app.certgov.app/mcp \
  --header "Authorization: Bearer <your-api-key>"

Verify:

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):

{
  "mcpServers": {
    "certforge": {
      "url": "https://app.certgov.app/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Restart Cursor. CertForge tools appear in the agent panel.

Setup: Zed

Add to ~/.config/zed/settings.json:

{
  "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:

npx -y mcp-bridge \
  --mcp-url https://app.certgov.app/mcp \
  --mcp-header "Authorization: Bearer <your-api-key>" \
  --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

# List available tools
curl -s -X POST https://app.certgov.app/mcp \
  -H "Authorization: Bearer <your-api-key>" \
  -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 <your-api-key>" \
  -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 <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_org_summary","arguments":{}}}' | jq .

​Overview

​Prerequisites

​Endpoint

​Available Tools

​Certificates & Audit

​Governance — Query

​Diagnostics

​Setup Guidance

​Action Tools — Create (two-step)

​Feedback

​Example: Diagnosing an ACME Issuance Failure

​Example: Certificate Security Rating

​Two-Step Confirmation

​Step 1 — Preview (default)

​Step 2 — Execute

​Example: End-to-End nginx Setup

​Setup: Claude Desktop

​Setup: Claude Code (CLI)

​Setup: Cursor

​Setup: Zed

​Setup: OpenAI-compatible clients (Grok, GPT-4o, etc.)

​Compatible Clients

​Analytics & Unsolved Queries

​Testing the Connection