Skip to content

agent-plugin-mcp-valid

Agent Plugins mcp.json must conform to the 1.0.0 schema and semantics
Severity error (auto)
Autofix -
Since v0.18.0
Repo Types agent-plugin
Category Agent Plugins

Agent Plugins define a portable mcp.json format at the plugin root. This rule validates that format against the Agent Plugins 1.0.0 specification while preserving its component and per-server failure boundaries.

The file is optional. When present, it must be a regular file contained by the plugin root and contain:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {}
}

The MCP schema version must match the manifest schema version declared by plugin.json. Invalid JSON, an unsupported or mismatched schema, and invalid top-level structure disable MCP for that plugin but do not invalidate its skills. An invalid server entry is reported independently so valid sibling servers remain usable.

Server variants

Each server is one closed variant:

  • stdio requires a non-empty command, and may define string-array args, string-map env, and string cwd.
  • streamable-http and sse require a non-empty url, and may define a string-map headers.

A stdio command is one executable token: either a bare executable name or a package-relative path beginning with ./. A bare command containing whitespace (such as node --eval) is rejected — supply arguments through args — and a ./ path must name a file, not a directory. Package-relative commands must remain inside the resolved plugin root. args and environment values are opaque strings for path handling, even when they contain ...

An explicit cwd must begin with ./, ${PLUGIN_ROOT}, or ${PLUGIN_DATA} and remain inside the selected root after the recognized placeholder is expanded. Plugins cannot set the reserved PLUGIN_ROOT or PLUGIN_DATA environment keys themselves.

Remote URLs must be absolute HTTP(S) URLs with a host and no user information or fragment. Non-loopback endpoints require HTTPS; plain HTTP is accepted only for localhost or a loopback IP literal. Header names and values must be valid HTTP fields, and duplicate names are rejected case-insensitively.

Configured env values and remote headers are visible package data, not a portable secret mechanism. They must not embed credentials or other secrets. The rule conservatively reports recognized structured tokens and values under obvious credential-bearing environment or header names, while accepting clear placeholder and variable-reference values. Extend the recognized placeholder markers with additional-placeholders. Diagnostics identify the affected mapping key but never include its value.

Agent Plugin mcp.json nodes remain visible to the opt-in mcp-prohibited policy rule. The generic mcp-valid-json rule stands down for this format whenever this rule can run, so the two validators never issue contradictory or duplicate schema findings; under a forced non-agent --type, the generic rule covers the file instead.

How to fix

Keep the file at the plugin root, declare the canonical schema, and correct only the failing server when the top-level document remains valid. Put bundled executables behind a ./ path, pass arguments separately, use HTTPS for remote services, and let the client provide PLUGIN_ROOT and PLUGIN_DATA. Remove credentials from env and headers; authorization, credential storage, and generated authorization headers are client-managed.

Configuration

rules:
  agent-plugin-mcp-valid:
    enabled: auto  # true | false | auto
    severity: error
Parameter Description Default
additional-placeholders Extra case-insensitive substrings that mark a generic credential value as a placeholder (suppressing the violation) []

Run skillsaw explain agent-plugin-mcp-valid to see this documentation and the rule's effective configuration in your terminal.