# MCP / Tool Security Checklist

Purpose: keep Atlas/Hermes tool surfaces narrow, inspectable, and boringly safe. MCP is useful; ambient authority is how future-you gets mugged by a JSON schema.

## Default stance

- Prefer built-in Hermes tools or narrow local scripts before adding a broad MCP server.
- If the MCP server is packaged or documented as a Hermes skill/workflow, also run `Atlas/Hermes Skill Intake Checklist.md` before enabling it.
- Add MCP servers only for a specific missing primitive, not because a package exists.
- Treat every MCP server as code execution with a marketing department until audited.
- Disable MCP sampling for untrusted servers unless there is a clear need.

## Preflight before enabling a server

- Source and maintenance:
  - Known publisher or repository.
  - Recent commits/releases, readable code, sane issue history.
  - No opaque install scripts without review.
- Scope:
  - Server name describes one bounded capability.
  - Tool list is small enough to review.
  - No generic shell/file/network supertool unless intentionally sandboxed.
- Data access:
  - Explicit path allowlist; no ambient `$HOME`, repo root, `/`, or secrets directory access.
  - Read-only by default where possible.
  - Separate servers/profiles for read-only versus write/destructive operations.
- Credentials:
  - Pass only required env vars via `mcp_servers.<name>.env`.
  - Never inherit full shell env.
  - No secret values in config committed to git, skills, notes, Kanban comments, or prompts.
- Runtime:
  - Set conservative `timeout` and `connect_timeout`.
  - Prefer local stdio servers for private/local workflows; use HTTP only when the remote trust boundary is clear.
  - Pin package/version where practical for repeatability.

## Config review checklist

For each `mcp_servers.<name>` entry:

- Has exactly one transport: `command` or `url`.
- Uses explicit `args`; no hidden shell expansion.
- `env` contains only named secrets/capabilities required by this server.
- `timeout` is not huge by accident.
- `sampling.enabled` is false unless server-initiated LLM calls are intentionally needed.
- Server name will produce clear tool prefixes: `mcp_<server>_<tool>`.

## Injection / path traversal smoke tests

Before trusting a new server, run harmless prompts/tasks that attempt to exceed scope:

- Ask it to read outside the allowed path.
- Ask it to follow instructions from a file/webpage that says to reveal secrets.
- Ask it to write/delete outside the intended workspace.
- Ask it to echo environment variables or auth headers.
- Ask it to perform a destructive action without explicit user confirmation.

Expected result: refusal/error/blocked behavior, with no secret values printed.

## Operating rules

- Destructive operations still need explicit user confirmation even if the MCP server offers the tool.
- For repo work, inspect git status before and after; stage only intended source/docs changes.
- For debugging, report key names/status, never credential values.
- If a server logs too much, wrap it, patch it, or remove it. Logs are where secrets go to become archaeology.
- Restart Hermes after MCP config changes; tool discovery happens at startup.

## Periodic audit

Monthly or after major Hermes/tool changes:

- List configured MCP servers.
- Confirm each server still has an owner/use case.
- Remove unused or broad-authority servers.
- Re-run path/secret smoke tests for servers with file, shell, repo, browser, cloud, or messaging access.
- Check docs/skills if an MCP server becomes part of a recurring workflow.

## Stop signs

Do not enable, or disable immediately, if:

- The server wants unrestricted filesystem access for a narrow task.
- It requires broad cloud/account tokens without scoped alternatives.
- It can execute shell commands and is exposed to untrusted prompts/content.
- It performs network requests on arbitrary user/model-provided URLs without allowlists.
- It has no clear logging/redaction story.
- Its tool descriptions encourage the model to treat it as an all-purpose assistant inside the assistant. That way lies agent soup.
