Scan MCP tool permissions

What this guide covers

An MCP-connected agent can expose filesystem access, database queries, or commands through its tools. Foo Guard helps review the capabilities you declare in an agent configuration before deploying changes.

This is a static configuration assessment. Foo Guard does not start MCP servers, connect to their endpoints, call tools, or test runtime behavior. A top-level mcpServers block alone is not a supported tool inventory: declare the tools and their capabilities in the tools array. A server package name is not evidence that a particular dangerous capability exists.

Prepare a configuration

Use JSON or YAML in Foo Guard's supported agent format. The example below is synthetic and deliberately declares shell execution without approval so you can practice reviewing a finding. It is an assessment input, not an MCP server launch file.

id: mcp-review-example
name: MCP review example
owner: developer-experience
lifecycleState: development

tools:
  - name: workspace_read
    description: Read project files exposed by the filesystem server
    readsData: true
    accessesFilesystem: true
    writesData: false
    executesShell: false
    modifiesResources: false

  - name: command_runner
    description: Execute commands through an agent tool
    executesShell: true
    requiresApproval: false

permissions:
  - name: workspace.read
    scope: workspace:read
    resourceScope: local/project
    accessLevel: read
    production: false
    granted: true

autonomy:
  maxIterations: 10
  humanApprovalRequired: false
  unlimited: false
  canModifyOwnConfiguration: false

auditability:
  loggingEnabled: true
  tracingEnabled: true
  actionAttribution: true

Describe the actual capabilities available to your agent. Where relevant, declare accessesDatabase, arbitraryHttp, writesData, modifiesResources, destructive, and requiresApproval. Review permission scopes and credential handling alongside tools. Use credential references rather than real tokens, and remove secrets before submitting a configuration.

Run the assessment

1. Open the configuration scanner.
2. Select YAML and paste the example, or upload your own supported JSON or YAML file.
3. Run the scan and review the findings and configuration evidence.
4. Sign in if you want to save a sanitized assessment for later review.

For a local or CI workflow, follow the CLI setup guide, then scan the saved file:

fooguard scan ./agent.yaml --fail-on high

The CLI uses the Foo Guard service; it is not an offline MCP runtime test. Follow the CLI guide's plan and API-key requirements.

Review and remediate

For the shell tool, inspect the finding's rule, severity, and configuration path. Decide whether the agent needs shell execution at all. If it does, implement an approval boundary in the real agent and accurately reflect that control in the configuration.

Changing requiresApproval to true in a file does not create runtime enforcement. The configured control must also exist in your agent or tool implementation. Likewise, narrowing a permission declaration does not change credentials or permissions at the underlying service.

Rescan after making the actual remediation and updating the declaration. Other findings may remain: a single improvement does not guarantee a passing score. The deterministic rules engine decides findings, severity, and score; optional AI guidance only explains results.

Understand the limits

A passing assessment is not proof that a server is trustworthy or that an agent cannot be exploited. Undeclared capabilities, runtime prompt injection, tool output manipulation, and differences between the configuration and deployed system require additional review and testing.

Foo Guard does not automatically import arbitrary MCP tools/list responses or translate every vendor's server configuration into the normalized agent model. Check the declared input and the evidence behind each result.

Keep changes under review

Commit the supported agent configuration with your application and check it on pull requests. Keep its declarations aligned with changes to MCP tools and their actual permissions.