MCP server: "dangerous" actions & new tools

[cdelafuente-r7]

Description

This adds two related features to the MCP server:

1. Eight new MCP tools: that wrap the existing RPC endpoints for module and session control, backed by strict per-tool input validation.
2. A "dangerous actions" opt-in gate: Four of the eight tools can perform destructive operations. They now fail closed unless the operator explicitly enables them through one of three well-known paths (CLI flag, env var, or config file), with clearly documented precedence.

The eight new tools

Tool	RPC backing	Class	Annotations
msf_module_execute	module.execute	dangerous	read_only_hint: false, destructive_hint: true, idempotent_hint: false
msf_module_check	module.check	dangerous	read_only_hint: false, destructive_hint: true, idempotent_hint: false
msf_module_results	module.results	read-only	read_only_hint: true, destructive_hint: false, idempotent_hint: true
msf_running_stats	module.running_stats	read-only	read_only_hint: true, destructive_hint: false, idempotent_hint: true
msf_session_list	session.list	read-only	read_only_hint: true, destructive_hint: false, idempotent_hint: true
msf_session_stop	session.stop	dangerous	read_only_hint: false, destructive_hint: true, idempotent_hint: false
msf_session_read	session.interactive_read	read-only	read_only_hint: true, destructive_hint: false, idempotent_hint: true
msf_session_write	session.interactive_write	dangerous	read_only_hint: false, destructive_hint: true, idempotent_hint: false

Dangerous-mode gate

Dangerous tools fail closed. The gate is opened by any one of:

1. --enable-dangerous-actions on the msfmcpd CLI.
2. MSF_MCP_DANGEROUS_ACTIONS=true (or 1, yes, on) in the environment.
3. mcp.dangerous_actions: true in config/mcp_config.yaml (or the JSON-RPC variant).

Related Issue:
This resolves #21270.

IMPORTANT
This PR must be landed prior this one.

Breaking Changes

None

Reviewer Notes

This comes from this PR. I have extracted the MCP server changes here, as requested. The RPC/Framework-related code is in a separate PR.

Please only review the second commit (Add new MCP tools). The first one is handled by the other PR.

Verification Steps

Follow the steps in the documentation to setup and start the RPC and MCP servers.

The verification can be done manually using the MCP Inspector and test the MCP tools individually:

npx @modelcontextprotocol/inspector

Or you can use your favorite LLM to test live. (see the documentation)

I also included an integration test script that simulates a MCP client and performs standard operations with the MCP tools. The script can be found here: tools/dev/msfmcp_integration_test.rb

> ruby tools/dev/msfmcp_integration_test.rb --help
Usage: ruby tools/dev/msfmcp_integration_test.rb [options]
        --url URL                    MCP HTTP endpoint (default: http://127.0.0.1:3000)
        --token TOKEN                Bearer token (or set $MSF_MCP_TOKEN)
        --enable-dangerous           Run the dangerous-tool execution paths too
        --rhost IP                   RHOSTS target for dangerous tests (e.g. 192.0.2.10)
        --lhost IP                   LHOST for payload-bound dangerous tests
        --lport PORT                 LPORT for payload-bound dangerous tests
        --session-id N               Existing session id for session read test
        --check-module SPEC          Module spec for msf_module_check as TYPE:NAME
                                     (default: exploit:windows/smb/ms17_010_eternalblue)
        --check-option K=V           Datastore option for msf_module_check (repeatable, overrides defaults)
        --execute-module SPEC        Module spec for msf_module_execute as TYPE:NAME
                                     (default: auxiliary:scanner/portscan/tcp)
        --execute-option K=V         Datastore option for msf_module_execute (repeatable, overrides defaults)
        --exploit-timeout SEC        Seconds to wait for the exploit run to reach a terminal state (default: 120)
        --filter PAT                 Only run tests whose name matches PAT
    -v, --verbose                    Print full responses on failure
    -d, --debug                      Print the full HTTP request/response for every call (succeeds too)
    -h, --help                       Show this help

AI Usage Disclosure

AI was used to help designing and implementing these changes (Copilot).

Pre-Submission Checklist

• Included a corresponding documentation markdown file in documentation/modules (new modules only)
• No sensitive information (IP addresses, credentials, API keys, hashes) in code or documentation
• Tested on the target environment specified in the Environment section above
• Included RSpec tests for library changes (encouraged for lib/ changes)
• Read the CONTRIBUTING.md and module acceptance guidelines

Hardware and Complex Software Module Guidance

If your module targets specialized hardware (routers, IoT, PLCs, etc.) or complex software (licensed, multi-service, or multi-version), provide a pcap, screen recording, or video showing successful execution.

Email sanitized pcaps/recordings to msfdev@metasploit.com — remove real IPs, credentials, and hostnames before sending. If hardware/software is unavailable, explain in the PR description.

Responsiveness and PR Takeover Policy

We want every contribution to make it into the project. If approximately 2 weeks pass after a review request without a comment or code update from you, the team may take over the PR and complete the work on your behalf.

If this happens, you will remain credited as a co-author on the final commit — your contribution is always recognized.

This policy exists to keep the project moving forward. It is not a reflection on the quality of your work or your involvement. Life happens, and we would rather finish the work together than let a good contribution go stale.