Overview
The linter validates tool, resource, and prompt definitions against the MCP spec and framework conventions. It is build-time only — not invoked at server startup. It runs in two places:
| Entry point | When | On failure |
|---|---|---|
bun run lint:mcp |
Manual or CI | Imports every definition file, prints errors + warnings, exits non-zero on errors. A file that fails to import is an error (definition-import-failed), never a skip. |
bun run devcheck |
Pre-commit workflow | Wraps lint:mcp alongside typecheck, format, bun audit, bun outdated. |
Both surface the same LintReport from validateDefinitions() (exported from @cyanheads/mcp-ts-core/linter), plus two load errors the CLI raises itself, because validateDefinitions() only receives what already loaded: definition-import-failed and server-json-parse. Each diagnostic has a stable rule ID — that's the anchor you land on via the See: framework-skills/api-linter/SKILL.md#<rule> breadcrumb appended to every message.
Severity:
- error — MUST-level spec violation; blocks
devcheck. - warning — SHOULD-level or quality issue; logged but
devcheckcontinues.
Imports (if you need to run the linter programmatically):
import { validateDefinitions } from '@cyanheads/mcp-ts-core/linter';
import type { LintReport, LintDiagnostic } from '@cyanheads/mcp-ts-core/linter';
const report = validateDefinitions({ tools, resources, prompts, serverJson, packageJson });
if (!report.passed) process.exit(1);
Rule index
Grouped by family. Jump to any rule ID via its anchor.
| Family | Rules | Section |
|---|---|---|
| Definition | definition-invalid, definition-import-failed |
Definition rules |
| Format parity | format-parity, format-parity-threw, format-parity-walk-failed, format-parity-depth-limit |
Format parity |
| Schema | schema-is-object, describe-on-fields, schema-serializable, schema-unsatisfiable, header-param-designation, schema-root-meta-discarded |
Schema rules |
| Portability | schema-format-portability, schema-anyof-needs-type, schema-no-discriminator-keyword, schema-no-defs, schema-root-oneof-portability, schema-dialect-tag |
Portability rules |
| Names | name-required, name-format, name-unique |
Name rules |
| Tools | description-required, handler-required, auth-type, auth-scope-format, annotation-type, annotation-coherence, input-alias-conflict, meta-ui-type, meta-ui-resource-uri-required, meta-ui-resource-uri-scheme, app-tool-resource-pairing, canvas-consumer-missing |
Tool rules |
| Resources | uri-template-required, uri-template-valid, resource-name-not-uri, template-params-align |
Resource rules |
| Landing | landing-* (23 rules — shape, tagline, logo, links, repo, envExample, connectSnippets, theme) |
Landing config rules |
| Prompts | generate-required |
Prompt rules |
| Handler body | prefer-mcp-error-in-handler, prefer-error-factory, preserve-cause-on-rethrow, no-stringify-upstream-error |
Handler body rules |
| Error contract (structural) | error-contract-type, error-contract-empty, error-contract-entry-type, error-contract-code-type, error-contract-code-unknown, error-contract-code-unknown-error, error-contract-reason-required, error-contract-reason-format, error-contract-reason-unique, error-contract-when-required, error-contract-retryable-type, error-contract-severity-unknown, error-contract-recovery-required, error-contract-recovery-empty, error-contract-recovery-min-words |
Error contract rules |
| Error contract (conformance) | error-contract-conformance, error-contract-prefer-fail, error-contract-unthrown |
Error contract rules |
| Enrichment | enrichment-type, enrichment-empty, enrichment-field-type, enrichment-output-collision, enrichment-prefer-block, enrichment-trailer-render, enrichment-trailer-orphan, enrichment-trailer-unknown-field, capped-list-no-truncation |
Enrichment rules |
| server.json | ~40 rules prefixed server-json-* |
server.json rules |
Definition rules
definition-invalid
Severity: error
Fires when a tools, resources, or prompts array passed to validateDefinitions() contains a null/undefined entry (or any non-object value) instead of a definition object — e.g. a stray import or a conditional that yields undefined/false. The bad entry is reported as this diagnostic and skipped, rather than crashing the whole lint run.
Fix: remove the empty slot, or ensure every element of the array is a real definition object (e.g. [makeFooTool(), enabled ? makeBarTool() : null].filter(Boolean)).
definition-import-failed
Severity: error
Fires when a discovered definition file (*.tool.ts, *.resource.ts, *.prompt.ts, *.app-tool.ts, *.app-resource.ts under src/mcp-server/ or examples/mcp-server/) rejects on import(): a package that the file, or anything it imports, needs cannot be resolved, the file has a syntax error, or code throws at module load. None of that file's definitions can be checked, so the run fails rather than passing without them. The other files are still imported and linted, so one run reports every import failure alongside the rule diagnostics. The lint:mcp CLI (scripts/lint-mcp.ts) raises it; validateDefinitions() never does, since a programmatic caller does its own imports.
✗ [definition-import-failed] src/mcp-server/tools/definitions/query.tool.ts: Cannot find package '@duckdb/node-api' imported from …
Fix, by cause:
- An optional peer dependency imported at the top of the definition or of a service it imports: install the peer wherever
lint:mcpanddevcheckrun (adevDependencyis enough), or make the import lazy —await import('<pkg>')inside the handler or service method that uses it, so loading the definition never touches the package. The framework's own Tier 3 subpaths already lazy-load their peers; importing them from a definition needs nothing installed. - A throw at module load — reading config, constructing a client, or awaiting a network call at top level: move the work into
setup(), a service's init, or the handler. Definitions must import without side effects. - A syntax error: fix it.
devcheck's typecheck reports the same file with a location. - Running the script under plain
node: Node's type stripping does not rewrite a relative./x.jsspecifier tox.ts, so a definition that imports a sibling module fails to load. Run it under Bun —bun run lint:mcp, asdevcheckdoes.
Format parity
Why this family exists: different MCP clients forward different surfaces of a tool response to the model. Claude Code reads structuredContent (from your handler's return value, typed by output). Claude Desktop reads content[] (from your format() function). Every field must be visible on both surfaces or one class of client sees less than another. The linter enforces this by synthesizing a sample value where every leaf is a uniquely identifiable sentinel, calling format() once, then verifying each sentinel (or its key name, for permissive types like booleans) appears in the rendered text.
How leaves are matched. Two strategies, picked by leaf type:
| Leaf type | Sentinel | Match |
|---|---|---|
| string | MCPPARITY<path> — alphanumeric only |
substring, anywhere in the rendered text |
| number / int / bigint | a large distinctive integer | substring, retried against locale digit grouping (900,000,001 → 900000001) |
| boolean, enum member, literal, unrecognized type | the value the schema dictates (true, the first enum member, the literal) |
delimited token — must not be flanked by another alphanumeric or _; falls back to the field's key name as a whole word or camelCase segment |
Two consequences worth knowing when writing a format():
- The string sentinel is alphanumeric so escaping does not break it.
content[]is markdown carrying upstream text you do not control, so escaping at the render boundary is correct — and it leaves an alphanumeric probe byte-identical. Escape a character only where it would change rendering, per CommonMark/GFM rules: intraword_(snake_case), a<that cannot open a tag (p<0.05), and a[that cannot form a link all stay raw. Agents readcontent[]as text and copy spans out of it, so a blanket escape set turns into backslash noise in their output. Markdown escaping, HTML escaping, and URL encoding all pass. You never need to carve an exception into your escape set to keeplint:mcpgreen. - Schema-dictated values must render as their own token. A required
kind: z.enum(['full', 'outline'])thatformat()never renders is not satisfied by the lettersfullappearing inside a longer word elsewhere in the output —case_name_full,inactive,listing. Render the field, or render its key name as a label.
format-parity
Severity: error
Fires when format() does not render a field present in output. Emitted once per missing field; large schemas can produce many format-parity diagnostics from a single tool.
Primary fix: render the missing field in format(). For tools that return either a summary list or a detail view, declare one flat z.object with a kind discriminator and presence-based optional arms — tool() rejects a z.discriminatedUnion output root, and it does so before any lint rule runs, with a TypeError naming a field you never declared. Render each arm on presence, with independent if blocks, never else if: a flat object yields one synthetic sample with every arm populated at once, so a mutually exclusive formatter leaves the untaken arm's leaves unrendered and fails parity on each of them.
output: z.object({
kind: z.enum(['list', 'detail']).describe('Which arm this result carries'),
items: z.array(ItemSchema).optional().describe('Matching items — present when kind is "list"'),
item: ItemSchema.optional().describe('The item — present when kind is "detail"'),
history: z.array(HistoryEntry).optional().describe('Change history — present when kind is "detail"'),
}),
format: (result) => {
const lines = [`Kind: ${result.kind}`];
if (result.items) for (const i of result.items) lines.push(`- ${i.id} — ${i.name}`);
if (result.item) lines.push(`Item: ${result.item.id} — ${result.item.name}`);
if (result.history) for (const h of result.history) lines.push(` ${h.at}: ${h.note}`);
return [{ type: 'text', text: lines.join('\n') }];
}
A union nested below the root is fine — the walker does produce one sample per branch there. The constraint is the output root alone.
Escape hatch: if the output schema was over-typed for a genuinely dynamic upstream API (e.g., a third-party JSON blob whose shape you can't nail down), relax it:
output: z.object({}).passthrough()
passthrough() still flows the full payload to structuredContent without declaring each field, so the linter has nothing to check against and you're not maintaining aspirational typing.
Anti-pattern: summary-only format() like return [{ type: 'text', text: \Found ${n} items` }]. The sentinel walk will flag every field in the items array. Don't "fix" this by removing fields from output— that makesstructuredContent` clients blind too.
format-parity-threw
Severity: warning
Fires when format() throws while being called with a synthetic sample. The linter cannot verify parity because your formatter crashed before producing output.
Fix: format() must be total — render any valid value of the output schema without throwing. Common causes:
- Assuming an optional array is always present (
result.items.map(...)whenitemscould beundefined) - Dereferencing a discriminated-union branch without checking the discriminator
- Calling
toFixed()ortoISOString()on a value that could legitimately be any number/string
Add narrow guards. The linter feeds a synthetic but schema-valid value; if your formatter can't handle it, real inputs will eventually hit the same path.
format-parity-walk-failed
Severity: warning
Fires when the linter cannot walk the output schema to build a synthetic sample (usually because the schema uses an unusual composition the walker doesn't recognize). Parity is not verified for that tool — nothing is broken at runtime, but the check is silently disabled.
Fix: inspect the walker error message in the diagnostic. Usually caused by custom Zod extensions or mixing Zod 3 and 4 schema internals. File an issue against @cyanheads/mcp-ts-core with the schema shape — this is a linter gap, not user error.
format-parity-depth-limit
Severity: warning
Fires when an output field is nested deeper than the sentinel walker's depth limit (8). Everything at and below that path was not evaluated — parity for the subtree is unknown, not verified. Four array hops from the output root is enough to reach the limit, so it turns up on ordinary shapes, not just pathological ones.
A hop is not a path segment. The walker counts every descent, and a union / discriminated_union dispatch descends into each branch at depth + 1 while keeping the parent's path unchanged. So a union nested in the output shape spends a level that the reported path never shows, and a warned path can read as exactly 8 hops rather than 9. Count the unions when you are working out which field to flatten.
The bound exists because every array / union / record hop multiplies the variant set, and a self-referential schema would otherwise recurse forever. What changed is the reporting: an unevaluated subtree used to be indistinguishable from a field that resolved to nothing, so it read as a pass.
Fix: flatten the output shape so the field sits within the limit, or verify by hand that format() renders it (and treat the warning as the standing reminder that the linter is not covering it).
Schema rules
schema-is-object
Severity: error
Tool input/output and prompt args must be z.object({...}) at the top level (not z.string(), z.array(...), etc.). The MCP spec requires a keyed structure at the schema root.
Fix: wrap whatever you had in a single-key object:
// Wrong
input: z.array(z.string())
// Right
input: z.object({ items: z.array(z.string()).describe('List of items') })
One exception, on tool input only: a z.discriminatedUnion(...) of object variants is accepted, for a multi-mode tool with mutually exclusive argument sets. It advertises as {"type": "object", "oneOf": [...]} — the object requirement holds, and each branch keeps its own required list and const-tagged discriminator. A bare z.union(...) is still rejected: with no discriminator the model has no key to pick a branch by. Output roots stay object-only — the 2025-era projection rewrites a non-object output root and wraps structuredContent to match.
The other schema rules walk every variant, so a missing .describe(), a non-serializable type, or an unsatisfiable node inside one branch is reported at input|<i>.<field>.
describe-on-fields
Severity: warning
Every field in input, output, params, or args needs a .describe('...') call. Descriptions ship to the client and the LLM — missing ones make tools harder to use correctly.
Fix: add .describe('...') to the paths the linter flags. The diagnostic names which path is missing a description (e.g., input.filters.status).
Recursion rules — the linter walks selectively; primitive array elements are intentionally skipped. Knowing what's walked prevents over-application of describes that end up as noise in the generated JSON Schema.
| Schema position | Walked? | Describe required on inner? |
|---|---|---|
z.object({ ... }) field |
Yes | Yes, on each field |
z.array(compound) element — object, array, or union |
Yes | Yes, on the element |
z.array(primitive) element — string, number, enum, regex-branded primitive, etc. |
No | No — outer array describe is sufficient |
z.union([a, b, ...]) non-literal option |
Yes | Yes, on each option |
z.union([..., z.literal(X), ...]) literal option |
No | No — outer union describe is sufficient |
A tool input root that is a z.discriminatedUnion(...) — its variant objects |
Yes, their fields | No, not on the variant itself — it is a root, and roots carry no describe |
A self-referential schema — a Zod 4 getter that returns the schema itself (get children() { return z.array(Node) }) — is walked once. The walk tracks the schemas on its current path and stops when one re-enters, so a missing .describe() inside the recursive schema is reported at its first occurrence, not once per level. The guard is per path: a non-recursive schema reused at two sibling paths is reported at both.
The asymmetry that catches agents: inside z.union([z.string(), z.array(z.string())]), the outer z.string() option does need a describe (unions walk non-literal options), but the z.string() inside the inner array does not (arrays don't walk primitive elements). If the linter didn't flag a path, don't add a describe there — the redundant describe ships to the JSON Schema as clutter.
Literal variants are exempt because they carry no independent semantic content — they're structural markers. The canonical case is form-client blank tolerance, where a z.literal('') variant is threaded into a union alongside a validated string so empty submissions from MCP Inspector / web UIs round-trip without breaking schema-level validation:
variable: z
.union([
z.literal(''), // form-client sentinel — no describe needed
z.string().max(50).regex(/^[a-z_][a-z0-9_]*$/i)
.describe('Identifier matching [a-zA-Z_][a-zA-Z0-9_]*, max 50 chars'),
])
.optional()
.describe('Variable name. Blank values from form-based clients are treated as omitted.'),
The outer describe on the union carries the semantic load; the non-literal variant still gets its own describe so the LLM sees the regex/length constraints in JSON Schema. Only the z.literal is skipped.
schema-serializable
Severity: error
Input/output schemas must use JSON-Schema-serializable Zod types only. The MCP SDK converts schemas to JSON Schema for tools/list; non-serializable types cause a hard runtime failure.
Disallowed: z.custom(), z.date(), z.transform(), z.bigint(), z.symbol(), z.void(), z.map(), z.set(), z.function(), z.nan().
Fix: use structural equivalents. Most common swap:
// Wrong
z.date()
// Right
z.string().describe('ISO 8601 timestamp, e.g., 2026-04-20T12:00:00Z')
Parse the string to a Date inside the handler if you need one.
schema-unsatisfiable
Severity: error
Fires when a node in the emitted JSON Schema describes an empty value set — a field no value can ever satisfy. Nothing downstream reports this: the tool registers, the schema is forwarded to the model, and the argument simply can never be populated.
Evaluated on the emitted schema rather than on the Zod schema, because the two disagree in exactly the case that matters most.
| What you wrote | What is emitted |
|---|---|
z.enum([1, 2, 3, 4, 5]) — a numeric array handed to a string-only constructor |
{"not": {}} |
z.enum([]) |
{"not": {}} |
.meta({ enum: [] }) / .meta({ oneOf: [] }) / .meta({ type: [] }) |
the empty set as written |
z.union([]) |
{"anyOf": []} |
z.never() |
{"not": {}} |
Fix: for a closed set of non-string values, use a multi-value literal — z.literal([1, 2, 3, 4, 5]) emits {"type": "number", "enum": [1, 2, 3, 4, 5]}. For an empty enum or union, the field has no legal values at all; drop it or give it real members.
Not flagged, deliberately: allOf: [] is vacuously true (matches everything), and empty required / properties / prefixItems are absent constraints rather than impossible ones.
header-param-designation
Severity: error
Fires when a tool's input carries an x-mcp-header designation — from headerParam(schema, 'Name') or a hand-written .meta({ 'x-mcp-header': 'Name' }) — that violates one of the constraints protocol revision 2026-07-28 places on it.
| Constraint | Example violation |
|---|---|
Statically reachable through a chain of properties keys |
A designation on an array element, a z.record() value, any field of a discriminated-union input root (the root advertises oneOf), or a schema hoisted into $defs by .meta({ id }) |
Primitive-typed property — string, integer, number, boolean |
headerParam(z.object({ … }), 'Region') |
| Non-empty RFC 9110 token | headerParam(z.string(), 'Bad Name') — spaces, control characters, and HTTP delimiters are all rejected |
| Case-insensitively unique across the whole input schema | 'Region' and 'REGION' on two sibling fields |
Evaluated on the emitted JSON Schema, which is the same input the SDK's own scan reads — so a verdict here is the SDK's verdict.
The message names the offending field in the linter's path vocabulary: input.rows[].region for an array element, input.map.<key> for a record value, input|0.region for a union branch.
Fix: move the designation to a top-level or nested object property. For a multi-mode tool, there is no placement that works — a union input root puts every field behind oneOf; flatten the schema or drop the designation.
Why it is an error, not a warning: the SDK enforces this with a console.warn. The tool still registers, and conforming Streamable HTTP clients then exclude it from tools/list — it silently disappears with nothing reporting the gap. tool() throws on the same condition at definition time, so this rule normally fires only for a definition assembled without the builder.
Silent when the schema cannot be converted to JSON Schema at all — that is schema-serializable's diagnostic.
schema-root-meta-discarded
Severity: warning
Fires when a .describe() or .meta() on a tool's input root was discarded by strictening, so the advertised inputSchema does not carry it.
Zod keys both calls to the schema instance, in z.globalRegistry. .strict() is catchall(z.never()) — a clone with no link back to the original — so the strictened schema tool() stores inherits no entry. Ordering is therefore load-bearing, and nothing in the type signature says so:
z.object({ … }).describe('An object root.') // lost — tool() strictens after
z.object({ … }).strict().describe('An object root.') // kept — already strict, returned untouched
The loss is otherwise invisible in every direction: describe-on-fields never asks a root to describe itself, and schema-anyof-needs-type reports on the metadata that survived, so a dropped .meta({ anyOf }) reads as no anyOf at all — which matters, because anyOf with per-branch type is the portable way to publish "one of these argument sets is required".
Fix: move .strict() ahead of .describe() / .meta() on the root. The message names what was discarded and where: input for an object or union root, input|<i> for a union variant (a union is rebuilt from its strictened options, so the union's own entry and each rebuilt variant's both go).
Silent when nothing was strictened — an explicit .strict(), .passthrough(), or .catchall(...) on the root or on every variant — which is exactly the case that advertises the metadata today. Also silent for a definition assembled without the tool() builder, since nothing strictened it.
Detection happens inside tool(), the only place both the authored and the strictened instance exist; by lint time the definition holds the clone, which carries no registry entry and no way back. The record rides a symbol-keyed, non-enumerable property, so Object.keys(definition), JSON.stringify(definition), tools/list, /.well-known/mcp.json, and _meta are all unchanged.
Whether the discarded description or metadata should instead reach the wire is a separate question — that changes the advertised bytes, so it is held.
Portability rules
MCP pins JSON Schema 2020-12 as the default dialect (SEP-1613), but LLM vendors accept different subsets. A schema that passes schema-serializable can still hard-fail at OpenAI's tool validator or silently lose fields at Gemini's API surface. These rules walk the emitted JSON Schema for patterns that break cross-vendor.
Three default-on, two opt-in. Promote opt-ins via MCP_LINT_PORTABILITY=strict (env) or validateDefinitions({ portability: 'strict' }) when targeting multi-vendor deployments.
| Rule | Severity | Default-on? |
|---|---|---|
schema-format-portability |
error | yes |
schema-anyof-needs-type |
warning | yes |
schema-no-discriminator-keyword |
warning | yes |
schema-no-defs |
warning | only when portability: 'strict' |
schema-dialect-tag |
warning | only when portability: 'strict' |
schema-format-portability
Severity: error
Fires when the emitted schema contains a format value outside the allowlist. Default = OpenAI's nine: date-time, time, date, duration, email, hostname, ipv4, ipv6, uuid — the strictest commonly-used target. OpenAI's tool validator hard-rejects unknown formats: the tool never registers and the model never sees it. Field report: cyanheads/git-mcp-server#47 (gpt-5-codex rejecting format: "uri" from z.url()).
Zod methods vs. the default allowlist:
| Zod call | Emitted format | Allowed? |
|---|---|---|
z.email(), z.uuid(), z.iso.datetime(), z.iso.date() |
email / uuid / date-time / date |
yes |
z.url() |
uri |
no — fires |
z.cuid(), z.cuid2(), z.ulid(), z.nanoid(), z.base64(), z.jwt() |
various | no — fires |
Fix: drop the format method, move the constraint into .describe() text where the model reads it:
// Wrong // Right
homepage: z.url().describe('Homepage') homepage: z.string().describe('Homepage (absolute URL)')
Override: widen the allowlist when targeting only vendors that accept the format:
validateDefinitions({ formatAllowlist: ['email', 'uuid', 'date-time', 'uri'], tools, resources, prompts });
schema-anyof-needs-type
Severity: warning
Fires when an anyOf/oneOf branch lacks a top-level type. Gemini rejects with 400: reference to undefined schema. Triggered by patterns like z.union([z.object({...}).nullable(), z.object({...})]) — the inner nullable emits a typeless anyOf.
Fix: prefer optionality via required-omission, or use z.discriminatedUnion for tagged unions — both emit branches with explicit type: "object".
schema-no-discriminator-keyword
Severity: warning
Fires when a schema carries the OpenAPI discriminator keyword. OpenAI silently ignores it; Gemini doesn't recognize it. Zod 4's z.discriminatedUnion emits the portable shape (oneOf of typed branches with const-tagged literals), so this rule mainly catches hand-built schemas attached via .meta({...}) or third-party-generated JSON Schema.
Fix: drop the discriminator meta — the const literals on each branch are how clients tell variants apart.
schema-no-defs
Severity: warning (only when portability: 'strict')
Fires when emitted output contains $defs or $ref. Gemini rejects these (400: reference to undefined schema). Typically caused by reused or recursive types built with z.lazy(...). Opt-in because SEP-1576 (token-bloat mitigation) is moving the community toward more $defs.
Fix: inline the recursive type with bounded depth, or accept the Gemini limitation if you target only Anthropic clients.
schema-root-oneof-portability
Severity: warning (only when portability: 'strict')
Fires when a tool's advertised inputSchema has a root-level oneOf — that is, when input is a z.discriminatedUnion(...). The emitted shape is valid 2020-12, every branch is a typed object, and the bytes are identical on both MCP protocol revisions. Vendor handling of a oneOf at the parameter root varies: a client that reads only type and properties sees a parameterless tool and drops the constraint silently rather than erroring, and Claude clients — the Anthropic Messages API rejects a top-level oneOf — rewrite the root to its first branch's properties, hiding every other mode from the model. Opt-in for now; whether it warns by default is tracked in #510.
Fix (for any tool that must work in Claude clients): flatten to a single z.object() with a discriminator field and optional per-mode fields, and validate the combination in the handler.
schema-dialect-tag
Severity: warning (only when portability: 'strict')
Fires when the top-level schema is missing $schema. SEP-1613 makes JSON Schema 2020-12 the default dialect, but explicit tagging ("$schema": "https://json-schema.org/draft/2020-12/schema") is forward-compatible — older SDK clients default to draft-07. Zod 4's toJSONSchema always emits $schema, so this rule is a no-op for Zod-only servers; it exists as forward-compat for hand-built schemas (see SEP-834).
Name rules
name-required
Severity: error
Every tool, resource, and prompt definition needs a non-empty name string. For resources, an empty name also falls back to the URI template (see resource-name-not-uri).
name-format
Severity: error
Scope: tools only — resources and prompts are checked by name-required only.
Tool names must match ^[A-Za-z0-9._-]{1,128}$ (alphanumerics, dots, hyphens, underscores; 1–128 chars). Tools conventionally use snake_case.
Fix: rename to a valid identifier. If the legacy name is user-facing, keep title as the display string and use a valid name internally.
name-unique
Severity: error
Tool names, resource names, and prompt names must each be unique within their type. Duplicates would cause the client to see only one.
Fix: rename one, or consolidate into a single definition if they're actually the same tool.
Tool rules
description-required
Severity: warning
Every tool, resource, and prompt needs a non-empty description. This is what the client shows the LLM to decide whether to call the definition. A missing description dramatically hurts selection accuracy.
Also applies to resources and prompts (same rule ID, different definitionType).
Fix: write a single cohesive paragraph. Prose, not bullet lists. Descriptions render inline in most clients.
handler-required
Severity: error
Every tool must have a handler function. Every resource must have a handler. Definitions without handlers can't do anything at runtime.
Also applies to resources (same rule ID, different definitionType).
auth-type
Severity: error
auth must be an array of strings. A single string or other shape is rejected.
// Wrong
auth: 'tool:my_tool:read'
// Right
auth: ['tool:my_tool:read']
auth-scope-format
Severity: error
Every element in auth must be a non-empty string. Empty strings in the array are rejected — they'd match anything.
annotation-type
Severity: warning
annotations hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) must be booleans. Strings like 'yes' or numbers are rejected — the MCP spec defines these as booleans and clients may type-check.
annotation-coherence
Severity: warning
Catches readOnlyHint: true with any explicit destructiveHint value (even false) — the destructive hint is meaningless on a read-only tool, so its presence signals authoring confusion. Drop destructiveHint entirely when the tool is read-only.
input-alias-conflict
Severity: error
Fires when a tool's inputAliases cannot resolve to exactly one declared input key. An alias is a one-to-one mapping fixed ahead of time — the reason it is accepted where nearest-key matching is not — so an alias resolving to none or to more than one is a definition error, not a runtime one. The runtime declines an ambiguous rewrite silently and the caller sees the ordinary strict rejection, which reads as the alias simply not working.
Six conditions, all decidable from the definition:
| Condition | Example |
|---|---|
| An alias must not equal a declared key | input: z.object({ q, query }) with inputAliases: { q: 'query' } — a declared key is never rewritten, so the alias can never fire |
| An alias's target must be a declared key | inputAliases: { q: 'searchQuery' } when the schema declares query |
An alias's target must not be headerParam-designated |
inputAliases: { region: 'regionCode' } with regionCode: headerParam(z.string(), 'Region') — the rewrite never targets a header-mirrored field, since the SDK checks the Mcp-Param-Region header against the body the caller sent, so the caller gets Unknown key region |
| Two declared keys must not case-fold to one name | z.object({ maxResults, max_results }) — no alias can resolve between them |
| An alias must not case-fold to a declared key other than its target | inputAliases: { max_results: 'query' } alongside a declared maxResults |
| Two aliases must not case-fold to one name with different targets | inputAliases: { 'search-term': 'query', search_term: 'maxResults' } |
Case-folding strips - and _ and lowercases — the same fold the runtime rewrite applies, so the rule and the runtime cannot disagree. On a discriminated-union root, every variant's keys count as declared: a rewrite resolves against the selected variant, so an alias naming a key no variant declares can never fire. The header check reads each variant's own designations, so an alias onto a designated field inside one variant is reported beside that variant's header-param-designation error; a designation deeper than the root never blocks an alias, which only ever names a root key.
Fix: point the alias at an existing key, rename the key it shadows, or drop the alias. For a header target, drop the alias or the headerParam designation — the field cannot be both. Also fires when inputAliases is not an object of non-empty string targets.
Silent when no inputAliases is declared — the case-style half needs no declaration and declines ambiguity on its own.
meta-ui-type
Severity: error (MCP Apps tools only)
When a tool declares _meta.ui, that field must be an object. null, arrays, or primitives are rejected.
meta-ui-resource-uri-required
Severity: error (MCP Apps tools only)
_meta.ui.resourceUri must be a non-empty string. This is the URI the client resolves to load the app UI.
meta-ui-resource-uri-scheme
Severity: warning (MCP Apps tools only)
_meta.ui.resourceUri should use the ui:// scheme. Other schemes (like https://) work but are discouraged — the ui:// convention signals the resource is meant to be hosted by the MCP server, not fetched externally.
app-tool-resource-pairing
Severity: warning (MCP Apps tools only)
An app tool's _meta.ui.resourceUri must match the uriTemplate of a registered resource. This catches the common mistake of renaming one side of the pair and forgetting the other.
Fix: either correct the resourceUri to match an existing resource, or register the resource it references. Use the add-app-tool skill's paired scaffold to avoid this.
canvas-consumer-missing
Severity: warning
Fires when the registered tool set contains at least one tool whose output schema has a depth-0 field named canvas_id or canvasId, but no consumer tool is registered — that is, no tool name ends with _dataframe_query and no extra names are listed in canvasConsumers.
A canvas token with no query path is dead output: the agent receives the token but has no tool to send it to. The fix runs in either direction:
- Complete the integration — add the standard
<prefix>_dataframe_queryand<prefix>_dataframe_describeconsumers (seeapi-canvas). - Remove the staging — when the data isn't row-shaped (nested, heterogeneous, single-record payloads), SQL access adds nothing. Drop the DataCanvas integration rather than adding tools to justify it.
Knob: suppress via LintInput.canvasConsumers:
// Accept a non-standard query tool name:
validateDefinitions({ tools, canvasConsumers: ['my_sql_query'] });
// Disable the rule entirely:
validateDefinitions({ tools, canvasConsumers: false });
Env var: MCP_LINT_CANVAS_CONSUMERS — comma-separated tool names; the literal false disables. A programmatic LintInput.canvasConsumers takes precedence over the env var. Servers that need the knob set MCP_LINT_CANVAS_CONSUMERS=my_query_tool in their .env or CI environment.
Resource rules
uri-template-required
Severity: error
Every resource needs a non-empty uriTemplate string. The URI template is the resource's primary identifier.
uri-template-valid
Severity: error
uriTemplate must be syntactically valid per RFC 6570: balanced braces, non-empty variable names. test://{id/data (unbalanced) and test://{}/data (empty variable) are rejected.
resource-name-not-uri
Severity: warning
Warns when the resource's name defaults to the URI template because no explicit name was provided. URIs make poor display names — clients often show them verbatim.
Fix: add a short name field:
resource('myscheme://{id}/data', {
name: 'Item data', // <-- add this
// ...
})
template-params-align
Severity: error
Every variable in the URI template must appear as a key in the params schema. test://{itemId}/data with params: z.object({ item_id: ... }) is rejected — casing mismatches count. The check is template → schema only; extra schema keys not referenced by the template are not flagged.
Fix: rename one side so they match exactly. The error message names which variables are on which side.
Prompt rules
generate-required
Severity: error
Every prompt needs a generate function that returns the message array. Prompts without generate have nothing to produce.
(Prompts also share name-* and description-required rules from their respective families.)
server.json rules
Validates the server.json manifest at project root against the MCP server manifest spec. Every rule below fires only when a server.json is present.
| Rule ID | Severity | What it checks |
|---|---|---|
server-json-parse |
error | server.json exists but does not parse as JSON, so none of the rules below can run. Raised by the lint:mcp CLI, which reads the file; a missing server.json is skipped |
server-json-type |
error | server.json must be a JSON object, not an array or primitive |
server-json-name-required |
error | name must be present and non-empty |
server-json-name-length |
error | name length 3–200 characters |
server-json-name-format |
error | `nam |
…(truncated)