MCP security starts before an agent connects to a server. A configuration can launch a local executable or point to a remote service, and the tools it exposes can influence both the agent's decisions and the resources it can access. Review the executable, permissions, and tool metadata together.
| Review question | Practical answer |
|---|---|
| Can I inspect a config without running its server? | Yes. Read supplied files and source as data; avoid launchers and installers during static review. |
| Does a clean scan approve connection? | No. It means no enabled heuristic matched the supplied text. |
| Does one version pin cover the config? | No. Review every server, package, wrapper, and image independently. |
| Are local stdio and HTTP servers equivalent? | No. A subprocess and an HTTP service expose different access and authorization boundaries. |
| What if source or tool manifests are unavailable? | Record the missing evidence and limit the recommendation to the reviewed artifacts. |
| When should the review be repeated? | After changes to packages, configuration, permissions, endpoint ownership, or tool definitions. |
What can go wrong?
Four useful review categories are tool poisoning, tool shadowing, rug pulls, and harmful combinations of otherwise ordinary tools. These categories are a practical way to organize questions, not an exhaustive protocol threat model.
| Risk | Example to look for | Review response |
|---|---|---|
| Tool poisoning | A description asks the agent to include unrelated local credentials in an argument | Inspect the requested data and destination; do not follow the embedded instruction |
| Tool shadowing | A server imitates another tool's name or tells the agent how to use a different server | Check server identity, client namespacing, and cross-server instructions |
| Rug pull | Previously reviewed tool metadata or executable content changes | Compare revisions, pin artifacts where possible, and review the changed behavior |
| Harmful tool sequence | A file reader supplies private content to a publishing tool | Review the combined data flow and permissions, then observe authorized use |
The MCP tool specification defines descriptions, schemas, and annotations, and requires clients to treat annotations from untrusted servers as untrusted. A label such as read-only is evidence of what the server claims, not proof of what its code does. Model-visible prose deserves the same attention as executable arguments.
For the broader agent context boundary, see securing AI coding assistants. Instructions bundled as skills need their own skill specification and security review.
How do you review before connection?
Start with a per-server evidence record. A useful record includes client name, config path, server name, transport, command or endpoint, source revision, artifact version or digest, supplied tool manifest, and review date. Preserve evidence locations while redacting credentials in environment values, headers, and URLs.
Read config files, manifests, lockfiles, and available implementation as text. Do not run npx, uvx, a Docker image, or an installer to obtain metadata for a static review. A supplied remote URL is also not permission to probe it. The MCP security guidance identifies local launch commands and downloaded server code as execution risks; inspecting their text is a separate operation from running them. MCP local server security guidance.
Check each executable and pin
For each entry, resolve the package identity, version constraint, executable arguments, working directory, wrapper scripts, and install hooks visible in the supplied material. Distinguish a package version from a verified artifact digest and from evidence that the publisher is trusted. Git branches and container tags can move; a pin also does not freeze a remote backend or external content fetched by the server.
The following is an illustrative review fixture, with fictional package names. It is valid JSON, not an installation recommendation:
{
"mcpServers": {
"reviewed-files": {
"command": "npx",
"args": ["--yes", "@example/[email protected]"]
},
"unreviewed-mail": {
"command": "npx",
"args": ["--yes", "@example/mail-mcp"]
}
}
}
The second entry is unpinned even though the first includes @1.2.3. Beam's current coarse npx check searches the whole input for a numeric version pattern, so the first entry can mask the second. It does not resolve each package or verify its integrity. Review mixed pins manually, along with uvx, containers, aliases, and wrappers.
Map effective access
Build a capability map from the config and implementation: readable paths, writable paths, process execution, network destinations, credential scopes, and external effects. Record unknowns when a wrapper, dependency, or remote implementation is unavailable.
For a local process, inspect inherited environment access and the launch environment. For containers, inspect mounts, privileges, network access, and any container engine socket. A server that only needs a project directory should not receive a home-directory mount merely because setup documentation suggests it.
An MCP root is not an operating-system sandbox. The roots specification describes client-provided filesystem boundaries and asks servers to respect them; it does not itself remove process access to other paths. Review actual filesystem permissions and isolation separately. MCP roots specification.
If the integration also loads models, adapters, or local inference components, include those in an AI asset inventory and model security review.
Read tool manifests as untrusted content
Review supplied names, descriptions, input and output schemas, prompts, resource templates, and sample results. Flag instructions that redirect the task, invoke unrelated tools, hide activity, or request data that the advertised operation does not need. Compare descriptions and schemas with the previously reviewed revision when one exists.
Check implementation evidence for the advertised capability. A narrow input schema can improve validation without proving the caller is authorized to use a resource. A tool named read_project still needs review if its implementation accepts arbitrary paths or executes a shell command.
Record how the client distinguishes tools from different servers. A name collision is a review question, not automatic proof that one tool overrides another: the actual effect depends on client behavior.
Which HTTP checks matter?
MCP 2025-11-25 defines stdio as a client-launched subprocess and Streamable HTTP as communication with an independent server. Its transport security requirements include validating incoming Origin headers, rejecting invalid origins with HTTP 403, and recommendations to bind local servers to localhost and authenticate connections. A URL in a config cannot prove these controls work. MCP transport specification.
For an HTTP integration using the specification's OAuth flow, inspect token validation, issuer and audience handling, expiry, and scopes. Tokens must be intended for that MCP server; forwarding the client's token unchanged to a downstream API is prohibited. Also inspect exact redirect URI matching, PKCE, and per-client consent at applicable proxies. Missing OAuth on a direct stdio integration is not itself a finding: the authorization specification addresses HTTP and directs stdio implementations toward credentials from their environment. MCP authorization specification.
Discovery is a separate network boundary. Review validation of OAuth discovery URLs and redirect destinations, restrictions on private and reserved addresses, and protection against DNS changes between validation and connection. Treat session IDs as state identifiers: authenticated requests still need validation, and sessions should be bound to the authenticated user. Session possession must not substitute for authentication. MCP SSRF and session security guidance.
Use these as evidence questions. If the only supplied artifact is mcp.json, report HTTP authorization and runtime isolation as unverified. Do not turn missing implementation evidence into either a confirmed vulnerability or a clean bill of health.
How do you scan with Beam?
With a trusted Beam CLI already installed, scan a supplied config or tool manifest locally:
beam scan /absolute/path/mcp.json --mcp
beam scan /absolute/path/tools.json --mcp
The offline path reads the file and applies built-in text heuristics plus configured custom rules. It does not start the MCP server or invoke its tools. The command behavior described here was checked against Beam CLI src/cli.ts, src/client.ts, and src/core.ts on September 14, 2026.
--mcp requires valid JSON with an object or array at the top level. This is a syntax and broad shape check, not a client-specific config validator. For TOML, YAML, or JSONC, review the original directly. If a JSON projection helps, use a trusted parser and record source locations and omissions; removing comments with a regular expression can corrupt strings.
Input must be nonempty and within both limits: 500,000 JavaScript string code units for the scan text and 2,000,000 bytes for the file read. Preserve complete server entries and review context when splitting larger material.
Read the JSON findings array even when the command exits successfully. Success indicates command completion, not the absence of findings. An empty array only means the enabled patterns did not match: a config can omit the malicious behavior entirely, and novel or indirect instructions can escape a text heuristic.
The reverse is also possible. A security document quoting a dangerous command may trigger a legitimate pattern match without asking anyone to execute it. Review the evidence and surrounding intent instead of treating every match as a verdict.
Omit --save for an offline review. That flag sends the input to the configured running collector for report persistence; use it only when persistence is part of the task. The scan itself does not enforce MCP permissions or certify protocol conformance.
When are runtime tests appropriate?
Run integration tests only within a separately authorized scope. Record the exact launch command or endpoint, permitted tool calls, expected effects, and resource limits before starting. Tool listing already starts or contacts a server; it is not a static inspection step.
Use synthetic files and temporary credentials in an isolated test environment with minimal mounts and network access. If the agreed test is a file read, specify the fixture path and expected output. If it includes a write, specify the disposable target and cleanup. Test rejection of unauthorized operations only where that negative test is part of the agreed scope.
Stop on unexpected access or external effects. Record what happened and the evidence gap rather than granting more privileges to make the test pass. A successful fixture test supports that specific behavior, not every future tool call.
What should the report say?
Return one row per server, with an explicit outcome: avoid connection, review required, or no blocking issue found in reviewed scope. The last outcome must name the inspected artifacts and remaining limits.
| Report field | Include |
|---|---|
| Identity and reproducibility | Client, server, transport, source revision, package version or image digest |
| Scope | Inspected config, source, manifest, dependencies, and any skipped material |
| Capabilities | Filesystem, process, network, credentials, and external effects |
| Findings | Severity, confidence, redacted evidence locations, likely effect, and smallest practical fix |
| Verification | Static evidence, observed runtime behavior, and untested claims separated clearly |
| Follow-up | Specific changes or missing evidence that require another review |
Continue with AI agent monitoring to understand what ongoing observation adds, and the vibe coding security checklist for day-to-day checks. Visit agentbeam.com for advanced monitoring and control, including further self-hosting and ongoing monitoring guidance. Review the controls supported by your installed integration; using a scanner does not enable them automatically.
Frequently asked questions
What is MCP tool poisoning?
It is tool metadata that tries to redirect the agent away from the user's task, conceal behavior, or transmit unrelated data. Inspect the requested action and trust boundary rather than treating imperative wording alone as proof of an attack.
Does pinning an MCP server make it safe?
No. A pin reduces unintended package changes; it does not establish publisher trust, freeze remote behavior, or prove the pinned code is safe. Review each executable and its dependencies independently.
Can a config scan verify OAuth or tool behavior?
No. It can inspect declared configuration and text patterns. Implementation evidence or separately authorized runtime tests are needed to assess token validation, user isolation, and actual tool effects.
Is an MCP filesystem root a sandbox?
No. Treat the declared root as intended scope and verify the process's actual permissions, mounts, and isolation separately.
Related reading
- Agent skills specification and security review
- AI asset inventory and model security
- AI agent security: securing coding assistants
- What is AI agent monitoring?
- Vibe coding security checklist
- MCP security with Beam
Protocol guidance was reviewed against MCP 2025-11-25 on September 14, 2026. Beam CLI behavior reflects the source inspected that day; a static scan is not a protocol certification or a guarantee of safety.
For repeatable reviews, set up Beam security skills and specialist sub-agents. After reviewing a server, use the deployment and incident-response guide to distinguish configuration evidence from runtime observations.