pkinative-mcp

Overview Schema Source Related Servers Discussions Admin

Check certificate name (RFC 6125 host / IP identity, or one name match)

check_certificate_name

Read-onlyIdempotent

Checks whether an X.509 certificate is valid for a hostname or IP under RFC 6125, or compares a presented DNS name against a reference name. Returns a match verdict with mismatch reasons.

Instructions

The RFC 6125 identity verdict, two forms. Certificate form: certificate + exactly one of host (DNS name as it appeared in the URL) / ip — is the certificate valid for that identity (subjectAltName dNSName / iPAddress; wildcards under allowWildcards, default true; allowCommonNameFallback, default false, reads a CN-only certificate's commonName and then needs chain — the issuing CAs, leaf's issuer first — so the CN is held to their dNSName name constraints as a SAN would be). Match form: presented (the certificate's dNSName, possibly a wildcard) + reference — one RFC 6125 §6.4 name comparison, no certificate. A negative verdict is valid:false + reasons[] (PKI_REASON_NAME_MISMATCH, …) in structuredContent — never isError. The name only: it is not trust (verify_certificate_chain with serverName is the full verdict), not validity, not revocation. Token-frugal: verbosity:'summary'.

Input Schema

Name	Required	Description	Default
`ip`	No	The reference IPv4 or IPv6 address. Exclusive with host.
`host`	No	The reference DNS name as it appeared in the URL (one trailing dot is ignored). Exclusive with ip.
`chain`	No	The issuing certificates, leaf's issuer first (every PEM block of every item is taken). Optional; read only by the commonName fallback, which holds a CN read as a host name to the dNSName name constraints of these CAs (without it the fallback refuses).
`fields`	No	Dot-paths to keep after verbosity (arrays map over elements); unmatched paths land in _meta.unmatchedFields.
`limits`	No	Raise pkinative's 22 named security bounds for this call (trusted input only; absent keys keep the engine defaults). A value above an operator ceiling (PKINATIVE_MCP_MAX_INPUT_BYTES, PKINATIVE_MCP_MAX_KDF_ITERATIONS, PKINATIVE_MCP_MAX_PATHS_EXPLORED) is LIMIT_CEILING_EXCEEDED; describe_engine lists the defaults and the ceilings.
`strict`	No	Escalate the first engine warning to a PKI_STRICT_DIAGNOSTIC error instead of listing it in diagnostics[].
`pemMode`	No	'strict' (RFC 7468 exactly, default) or 'lax' (tolerates whitespace, line length and RFC 1421 headers).	strict
`presented`	No	Match form: the certificate's dNSName, possibly a wildcard. With reference; exclusive with certificate / host / ip / chain.
`reference`	No	Match form: the reference host name.
`verbosity`	No	'summary' keeps the scalar fields only (token-frugal).	full
`certificate`	No	The certificate to judge (certificate form): exactly one of pem / derBase64 / path. With exactly one of host / ip. Exclusive with presented / reference.
`encodingRules`	No	'der' (strict X.690 DER, default) or 'ber' (indefinite / non-minimal lengths and constructed strings, as legacy CMS producers write).	der
`allowWildcards`	No	Accept a wildcard name (*.example.test) at all. Default true; false is right for an internal PKI that issues none.
`allowCommonNameFallback`	No	Fall back to the subject commonName when the certificate carries no dNSName and no iPAddress (CA/Browser Forum forbids CN-only certificates since 2017; needs chain). Default false.

Output Schema

Name	Required	Description
`form`	No
`match`	No	Match form: whether presented matches reference.
`valid`	No	The verdict (the match outcome in the match form). false is a negative verdict, never an error.
`reasons`	No	Why the verdict is negative (empty when valid): the engine PKI_REASON_* codes, each with the standard it cites and the path of the offending element. A reason is returned, never thrown.
`subject`	No	Certificate form: RFC 4514 subject of the certificate.
`presented`	No	Match form: the presented name.
`reference`	No	The reference identity judged.
`diagnostics`	No	Non-fatal concerns the engine raised (PKI_DIAG_*, de-duplicated, at most 200; explain_code explains one).
`reasonCodes`	No
`diagnosticCount`	No
`diagnosticCounts`	No	Occurrences per diagnostic code.
`diagnosticsTruncated`	No	true when distinct diagnostics beyond the 200 listed were dropped.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 27, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/idempotent annotations it discloses non-obvious behavior: a negative result is valid:false + reasons[] in structuredContent and never isError, defaults for allowWildcards and allowCommonNameFallback, and that the CN read is held to the issuing CAs' dNSName name constraints. It also flags verbosity:'summary' as the token-frugal path.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the two forms and the verdict semantics ahead of the caveats, and every clause carries information. The parenthetical chaining in the certificate-form sentence is heavy and would read better as separated sentences, but nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape needn't be restated, yet the description still covers the negative-verdict contract and reasons codes. For a 14-parameter tool with nested inputs, the exclusivity rules, defaults, and prerequisite wiring are all present — nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: `host` is 'as it appeared in the URL', `chain` is ordered leaf's issuer first and read only by the CN fallback, and the form-exclusivity rules (certificate with exactly one of host/ip, exclusive with presented/reference) are spelled out. Limits/strict/pemMode/encodingRules go unmentioned, which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (RFC 6125 identity verdict over a certificate or a name pair) and enumerates its two disjoint forms with the exact parameters that select each. It distinguishes itself from verify_certificate_chain and from validity/revocation checking, so an agent can place it among the siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: certificate form vs match form, plus a clear 'not this tool' clause naming verify_certificate_chain with serverName as the full verdict. The CN fallback condition (needs `chain`, refuses without it) is stated as a prerequisite rather than left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.