TLS Radar

Run a free, anonymous SSL/TLS scan against a hostname and return certificate details. No account required.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Hostname to scan (e.g. example.com). No scheme, no path."
    },
    "client_id": {
      "type": "string",
      "description": "Optional anonymous install id from ~/.config/tlsradar/install_id. Pass it for funnel attribution. If you omit it, the response's install_id is a fresh one to save there."
    }
  },
  "required": [
    "domain"
  ]
}

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "completed"
      ]
    },
    "share_token": {
      "type": "string"
    },
    "share_url": {
      "type": "string",
      "format": "uri"
    },
    "expiration_date": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "scanned_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "install_id": {
      "type": "string",
      "description": "Anonymous install id to persist locally and reuse."
    }
  },
  "required": [
    "domain",
    "status",
    "share_token",
    "share_url"
  ]
}

Start issuing a FREE 90-day Let's Encrypt certificate for a domain (no account required). Step 1 of 3. Pick a validation method with `challenge`: "dns-01" (default; publish a TXT record; covers apex + www) or "http-01" (serve a file over HTTP on port 80; issues the exact domain only). dns-01 with a DNS-provider API token is the most automatable; http-01 suits a server you control on port 80. Returns an order_id plus either dns_records (dns-01) or http_files (http-01) to put in place. Next: poll `check_certificate_propagation` until all_found, then call `finalize_certificate`. Strongly prefer the CSR path at finalize (the private key never leaves the user's machine). Issuing automatically offers the user ongoing monitoring by email once it completes - don't add a monitor manually afterward.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Apex domain, no scheme/www (e.g. example.com)."
    },
    "email": {
      "type": "string",
      "description": "Contact email for Let's Encrypt expiry notices and the monitoring handoff."
    },
    "challenge": {
      "type": "string",
      "enum": [
        "dns-01",
        "http-01"
      ],
      "description": "Validation method: dns-01 (default) or http-01."
    },
    "marketing_consent": {
      "type": "boolean",
      "description": "Only true if the user explicitly opts in to a free account + reminder email. Default false."
    },
    "client_id": {
      "type": "string",
      "description": "Optional anonymous install id from ~/.config/tlsradar/install_id (funnel attribution). If omitted, the response's install_id is a fresh one to save there."
    }
  },
  "required": [
    "domain",
    "email"
  ]
}

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string"
    },
    "domain": {
      "type": "string"
    },
    "challenge": {
      "type": "string"
    },
    "dns_records": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "TXT records to publish for dns-01."
    },
    "http_files": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Files to serve for http-01."
    },
    "resume_token": {
      "type": "string",
      "description": "Signed token to finalize past the backend's order TTL."
    },
    "install_id": {
      "type": "string"
    },
    "next_action": {
      "type": "string"
    }
  },
  "required": [
    "order_id",
    "domain",
    "challenge"
  ]
}

Check whether the DNS TXT records for a certificate order have propagated (Cloudflare/Google/Quad9). Step 2 of issuance - poll until all_found is true, then call finalize_certificate. Returns per-record resolver results.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order_id from create_certificate."
    }
  },
  "required": [
    "order_id"
  ]
}

{
  "type": "object",
  "properties": {
    "all_found": {
      "type": "boolean",
      "description": "True when every challenge record/file is in place."
    },
    "records": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Per-record propagation status."
    }
  },
  "additionalProperties": true
}

Finalize and issue a certificate order in one call: validates the DNS challenges, waits for Let's Encrypt, and returns the issued cert. Step 3 of issuance - call after check_certificate_propagation reports all_found. STRONGLY PREFER passing csr_pem (generate the key + CSR locally with openssl so the private key never leaves the machine). Returns leaf_pem/chain_pem/fullchain_pem. If you must, pass a passphrase instead to get a PKCS#12 bundle - but a CSR is safer. If it replies "still validating", DNS hasn't fully propagated: re-check check_certificate_propagation and call again. Needs a locally-generated CSR (csr_pem) - requires a local shell with openssl. On a surface without one (e.g. a Claude.ai custom connector) this can't complete; it returns guidance to finish in Claude Code/Cowork or the web form. Scanning and monitoring work everywhere. On success the structuredContent carries a `handoff` object - relay `handoff.message` to the user and do NOT separately call add_monitor; the cert→monitoring handoff is automatic and server-side.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order_id from create_certificate."
    },
    "csr_pem": {
      "type": "string",
      "description": "PEM CERTIFICATE REQUEST covering exactly {domain, www.domain}. Preferred - key stays local."
    },
    "passphrase": {
      "type": "string",
      "description": "Fallback only: ≥8 chars, protects a returned PKCS#12 bundle. Omit when using csr_pem."
    },
    "max_wait_seconds": {
      "type": "integer",
      "description": "How long to wait for validation server-side. Default 60, capped at 75."
    },
    "resume_token": {
      "type": "string",
      "description": "Optional. The resume_token from create_certificate; pass it to finalize an order whose row Beacon already purged (~24h)."
    }
  },
  "required": [
    "order_id"
  ]
}

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string"
    },
    "mode": {
      "type": "string"
    },
    "fullchain_pem": {
      "type": "string",
      "description": "Full certificate chain (PEM), present on success."
    },
    "leaf_pem": {
      "type": "string"
    },
    "chain_pem": {
      "type": "string"
    },
    "not_after": {
      "type": "string",
      "format": "date-time"
    },
    "handoff": {
      "type": "object",
      "description": "Cert->monitoring handoff; relay handoff.message and do not call add_monitor."
    }
  },
  "additionalProperties": true
}

Return the current state of a certificate order (dns_pending, validating, ready, completed, failed) and per-authorization Let's Encrypt statuses. Use it to resume an interrupted issuance.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order_id from create_certificate."
    }
  },
  "required": [
    "order_id"
  ]
}

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string"
    },
    "challenge": {
      "type": "string"
    },
    "fullchain_pem": {
      "type": "string",
      "description": "Present once the order is completed."
    }
  },
  "additionalProperties": true
}

Renew a certificate by cloning a recent order (requires the original order_id; Beacon purges orders after ~24h). Returns a new order_id and fresh DNS TXT records - then poll check_certificate_propagation and call finalize_certificate. If you don't have an order_id (the usual case at 90-day renewal time), call create_certificate for the domain instead; that IS the renewal.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The original order_id to clone. If you don't have one, use create_certificate instead."
    }
  },
  "required": [
    "order_id"
  ]
}

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string"
    },
    "challenge": {
      "type": "string"
    },
    "dns_records": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "http_files": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "state": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Return the current user's plan, limits, and usage so the client can render upgrade nudges proactively.

{
  "type": "object",
  "properties": {},
  "required": []
}

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "plan": {
      "type": "object",
      "description": "Plan tier and limits."
    },
    "usage": {
      "type": "object",
      "description": "Current usage against the plan limits."
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": true
}

List all certificates currently being monitored across the user's teams. If the response's structuredContent includes a `nudge` object, the user is at their monitor cap - surface it casually ONCE (lead with `nudge.recommended_upgrade`, mention `nudge.also_available` in one closing line); don't force it if it doesn't fit the conversation.

{
  "type": "object",
  "properties": {},
  "required": []
}

{
  "type": "object",
  "properties": {
    "monitors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "host_id": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "expiration_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "days_until_expiration": {
            "type": [
              "integer",
              "null"
            ]
          },
          "scan_group_id": {
            "type": "string"
          },
          "team_id": {
            "type": "string"
          }
        }
      }
    },
    "count": {
      "type": "integer"
    },
    "nudge": {
      "type": "object",
      "description": "Present only when an upgrade nudge is warranted."
    }
  },
  "required": [
    "monitors",
    "count"
  ]
}

Add a domain to ongoing certificate monitoring with expiry alerts. Requires authentication (the user runs /mcp once). If the plan's monitor limit is reached, the response's structuredContent carries a limit-reached payload - when relaying it, LEAD with `recommended_upgrade` (typically Starter, $9.99/mo), mention `also_available` tiers in a single closing line, and offer removing an existing monitor as the free alternative. Don't dump a full tier comparison; that's choice paralysis at the moment of action.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Hostname to monitor (e.g. example.com). No scheme, no path."
    }
  },
  "required": [
    "domain"
  ]
}

{
  "type": "object",
  "properties": {
    "host_id": {
      "type": "string"
    },
    "address": {
      "type": "string"
    },
    "scan_group_id": {
      "type": "string"
    },
    "team_id": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Add multiple domains to monitoring in one call. Returns a per-domain status so the caller can show partial-success outcomes. Honors the same plan-limit checks as add_monitor.

{
  "type": "object",
  "properties": {
    "domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of hostnames to monitor",
      "minItems": 1,
      "maxItems": 100
    }
  },
  "required": [
    "domains"
  ]
}

{
  "type": "object",
  "properties": {
    "requested": {
      "type": "integer"
    },
    "added": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Per-domain add status."
    },
    "team_id": {
      "type": "string"
    },
    "scan_group_id": {
      "type": "string"
    }
  },
  "required": [
    "requested",
    "added",
    "results"
  ]
}

Stop monitoring a domain. Accepts the domain name or the host_id returned by list_monitors.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain to stop monitoring"
    },
    "host_id": {
      "type": "string",
      "description": "UUID of the host (alternative to domain)"
    }
  }
}

{
  "type": "object",
  "properties": {
    "removed_address": {
      "type": "string"
    }
  },
  "required": [
    "removed_address"
  ]
}

Return monitored certificates expiring within N days. Defaults to 30. If the response's structuredContent includes a `nudge` object, the user is watching enough soon-to-expire certs to benefit from a higher tier - mention it casually ONCE (lead with `nudge.recommended_upgrade`); skip it if it doesn't fit.

{
  "type": "object",
  "properties": {
    "within": {
      "type": "integer",
      "description": "Days from now to look ahead",
      "minimum": 1,
      "maximum": 365,
      "default": 30
    }
  },
  "required": []
}

{
  "type": "object",
  "properties": {
    "entries": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "within_days": {
      "type": "integer"
    },
    "count": {
      "type": "integer"
    },
    "nudge": {
      "type": "object",
      "description": "Present only when an upgrade nudge is warranted."
    }
  },
  "required": [
    "entries",
    "within_days",
    "count"
  ]
}

Return recent scan results for a domain the user monitors. Useful for spotting issuer changes, grade drops, or vulnerability appearances over time.

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "Domain name as it appears in list_monitors"
    },
    "limit": {
      "type": "integer",
      "description": "Max results to return",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    }
  },
  "required": [
    "domain"
  ]
}

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "scanned_at": {
            "type": "string",
            "format": "date-time"
          },
          "scan_status": {
            "type": "string"
          },
          "expiration_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "grade": {
            "type": [
              "string",
              "null"
            ]
          },
          "issuer": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    },
    "count": {
      "type": "integer"
    }
  },
  "required": [
    "domain",
    "results",
    "count"
  ]
}

Dump the user's monitors as a JSON structure suitable for backup, migration, or infrastructure-as-code workflows. Tokens and PII are NEVER included - only domain configuration.

{
  "type": "object",
  "properties": {},
  "required": []
}

{
  "type": "object",
  "properties": {
    "version": {
      "type": "string"
    },
    "exported_at": {
      "type": "string",
      "format": "date-time"
    },
    "teams": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "version",
    "exported_at",
    "teams"
  ]
}

Create monitors from a JSON structure (typically produced by `export`). Skips domains the user is already monitoring; honors the plan's domain limit. Returns a per-domain status.

{
  "type": "object",
  "properties": {
    "payload": {
      "type": "object",
      "description": "Export payload, version 1.0. Use the `export` tool to generate one."
    }
  },
  "required": [
    "payload"
  ]
}

{
  "type": "object",
  "properties": {
    "requested": {
      "type": "integer"
    },
    "added": {
      "type": "integer"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Per-domain import status."
    }
  },
  "additionalProperties": true
}

Invite a user to a team by email. Defaults to the user's current team. Honors the plan's seat limit (returns the same upgrade payload as add_monitor when the cap is hit).

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Email address of the person to invite"
    },
    "team_id": {
      "type": "string",
      "description": "Team UUID; defaults to the current team"
    },
    "role": {
      "type": "string",
      "enum": [
        "guest",
        "admin"
      ],
      "default": "guest",
      "description": "Invitee role: guest or admin. Defaults to guest."
    }
  },
  "required": [
    "email"
  ]
}

{
  "type": "object",
  "properties": {
    "team_id": {
      "type": "string"
    },
    "team_name": {
      "type": "string"
    },
    "invited_email": {
      "type": "string"
    },
    "role": {
      "type": "string"
    }
  },
  "required": [
    "team_id",
    "invited_email",
    "role"
  ]
}