<!-- Generated by scripts/generate-site-content.py — do not edit by hand -->


# agent-plugin-mcp-valid

Agent Plugins mcp.json must conform to a supported schema and semantics

| | |
|---|---|
| **Severity** | error (auto) |
| **Autofix** | - |
| **Since** | v0.18.0 |
| **Repo Types** | agent-plugin |
| **Category** | [Agent Plugins](agent-plugins.md) |

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](https://agent-plugins.org/specification)
and the
[1.1.0 working draft](https://github.com/agentplugins/agent-plugins-spec/blob/ff8ab5e392cc87bd88d87c060815a87490e51003/spec/1.1.0.md)
while preserving their 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:

```json
{
  "$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`. Skillsaw supports the 1.0.0 and 1.1.0 schema pairs.
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

```yaml
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.*