Charter — AI-Agent Readiness Scanner

Use this guide when charter doctor reports one of the three MCP safety rules — AE-MCP-001, AE-MCP-002, or AE-MCP-003. MCP findings are often the highest-signal findings in a repo because they touch dependency integrity, origin trust, and remote authentication. For the reasoning behind each rule, see the MCP Safety Model.

charter explain AE-MCP-001   # compact rule metadata + link to full docs

AE-MCP-001 — Version pinning
AE-MCP-002 — Trusted remotes
AE-MCP-003 — Auth declaration

What it means: An MCP server entry is using a floating version (@latest, a semver range like ^1.2.3, a missing version entirely, or a deprecated/archived package). Charter requires exact version pins for supply-chain auditability.Example finding:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem@latest"]
    }
  }
}

Fix pattern — pin to an exact version:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem@latest"]
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem@0.6.2"]
    }
  }
}

Or let Charter apply a catalog-aware bump for you:

charter fix --rule AE-MCP-001 --dry-run   # review first
charter fix --rule AE-MCP-001             # apply

Deprecated packages (such as @modelcontextprotocol/server-github) cannot be auto-fixed — the migration path is a different package entirely. Charter provides the successor package name in the finding output. You must make that migration manually.

Common version problems Charter flags:

Pattern	Example	Status
Floating tag	`@latest`	Fail
Semver range	`^1.2.3` or `~1.2.3`	Fail
Missing version	`npx -y mcp-server-git`	Fail
Floating git ref	`git+https://...#main`	Fail
Exact pin	`@2026.1.14`	Pass

What it means: A remote MCP server URL’s hostname is not in Charter’s built-in catalog of known vendor-operated hosts, and it’s not in your repo’s charter.yaml allowlist. Charter flags unknown origins because remote MCP servers receive tool calls from your agent — the origin should be explicitly reviewed.Example finding: Charter reports a remote server at api.your-internal-tool.com that isn’t in the catalog.Resolution — add the host to your allowlist:

# charter.yaml
mcp:
  trustedRemotes:
    - "api.your-internal-tool.com"
    - "mcp.your-company.com"

Before adding a host, ask:

Is this a reviewed vendor host or your own trusted internal endpoint?
Should this remote actually be present in this repo at all?
Is this an unexpected entry that should be removed instead?

If the remote origin is unexpected or unreviewed, the correct resolution is to remove or replace the MCP server entry — not to add it to the allowlist. Only add hosts you have explicitly reviewed.

Hosts that are always exempt: local origins (localhost, 127.0.0.1, ::1) are never flagged regardless of allowlist contents.

What it means: A remote HTTP or SSE MCP server entry has no recognized auth header declared. Charter requires that remote servers declare authentication metadata so agents don’t silently make unauthenticated calls to external services.Example finding:

{
  "mcpServers": {
    "my-service": {
      "type": "http",
      "url": "https://your-mcp-server.com"
    }
  }
}

Fix — add an auth header to the server entry:

{
  "mcpServers": {
    "my-service": {
      "type": "http",
      "url": "https://your-mcp-server.com",
      "headers": {
        "Authorization": "${YOUR_API_KEY}"
      }
    }
  }
}

Use environment variable references (${VAR}) in headers — never literal credential values. Charter will flag a literal secret value as an AE-SEC-001 finding.

Accepted auth header names:

Header	Example
`Authorization`	`Bearer ${TOKEN}`
`X-Api-Key`	`${API_KEY}`
`Api-Key`	`${API_KEY}`
`X-Auth-Token`	`${AUTH_TOKEN}`

Any of the four accepted header names satisfies the rule. Charter does not validate the header value — only that a recognized auth header is declared.

Re-scan after changes

After editing your MCP config or charter.yaml:

charter doctor

To focus on MCP findings only while iterating:

charter doctor --rule AE-MCP-001,AE-MCP-002,AE-MCP-003

Fast investigation loop

charter doctor
charter explain AE-MCP-001
charter fix --rule AE-MCP-001 --dry-run
charter fix --rule AE-MCP-001
charter doctor

When not to suppress MCP findings

MCP findings are high-signal. Do not jump straight to suppression for findings that point at real supply-chain or trust problems. Suppress only when:

the repo intentionally carries a reviewed exception (e.g., a vendored test fixture)
you have a real reason and, for permanent suppressions, an approver

See Suppress a Finding for the full suppression workflow.

Next steps

MCP Safety Model

Why pinning, trusted remotes, and auth declaration are first-class readiness signals.

charter.yaml Reference

Declare reviewed remote hosts with mcp.trustedRemotes.

Use charter fix Safely

Apply the AE-MCP-001 pin bump without surprises.

Suppress a Finding

Record a reviewed MCP exception when one is justified.

​Re-scan after changes

​Fast investigation loop

​When not to suppress MCP findings

​Next steps

MCP Safety Model

charter.yaml Reference

Use charter fix Safely

Suppress a Finding

Re-scan after changes

Fast investigation loop

When not to suppress MCP findings

Next steps