Add Bearer Authentication to the MCP server plugin by zeroSteiner · Pull Request #21622 · rapid7/metasploit-framework

zeroSteiner · 2026-06-30T15:58:50Z

Description

This adds bearer authentication to the MCP server started by the plugin, bringing it inline with the same behavior added in #21527. The value meanings are the same, by default a random token is generated, if the user explicitly sets a blank value, authentication is disabled otherwise the token is used as-is.

Related Issue:

Breaking Changes

None

Reviewer Notes

Verification Steps

Use the same steps from #21527

- Load the plugin
- Start the server by default, see a randomly generated API token displayed
- Stop the server and restart it, adding AuthToken= to the end, see that now authentication is disabled
- Stop the server and restart it, adding AuthToken=whatever to the end, see that now authentication is enabled, and the token is not echoed back to the user. They gave it to us, they know it, we don't need to be logging it anywhere.

Test Evidence

msf exploit(windows/smb/psexec) > load mcp
[*] MCP plugin loaded. Use mcp start to start the server.
[*] Successfully loaded plugin: mcp
msf exploit(windows/smb/psexec) > mcp start
[*] Auto-started msgrpc - User: msf, Pass: 2MXwknnMf7zy
[*] MCP server listening on http://localhost:3000/
[*] Authentication: Bearer token (auto-generated)
[*]   Configure your MCP client with: Authorization: Bearer 43b93f53b68816f30dff19058fb4f676234e1943dc67ffa232b53b7a3e96733d
[*] Starting MCP server on HTTP transport...
msf exploit(windows/smb/psexec) > mcp stop
[*] MCP server stopped
msf exploit(windows/smb/psexec) > mcp start AuthToken=
key: "AuthToken" value: ""
[*] MCP server listening on http://localhost:3000/
[*] Authentication: disabled
[*] Starting MCP server on HTTP transport...
msf exploit(windows/smb/psexec) > mcp restart AuthToken=imhungryisitlunchtimeyet
[*] MCP server listening on http://localhost:3000/
[*] Authentication: enabled
[*] Starting MCP server on HTTP transport...
msf exploit(windows/smb/psexec) >

Environment

Field	Details
Operating System	Fedora
Target Software/Hardware	N/A
Docker Image / Vagrant Setup

AI Usage Disclosure

Did everything by hand.

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.

zeroSteiner · 2026-06-30T16:03:15Z

      @server_thread = framework.threads.spawn('MCPServer', false) do
-        @mcp_server.start(transport: :http, host: host, port: port)
+        print_status("Starting MCP server on HTTP transport...")
+        @mcp_server.start(transport: :http, host: host, port: port, auth_token: auth_token)
      end

      @started_at = Time.now
-      print_server_status(mcp_config)
+      print_status("MCP server listening on http://#{Rex::Socket.to_authority(mcp_config[:host], mcp_config[:port])}/")
+      if auth_token_generated
+        print_status("Authentication: Bearer token (auto-generated)")
+        print_status("  Configure your MCP client with: Authorization: Bearer #{auth_token}")
+      else
+        print_status("Authentication: #{auth_token ? 'enabled' : 'disabled'}")
+      end


While this code is duplicated, I took care so that what is printed is consistent between the plugin and the msfmcpd stand-alone utility, so it's not visually obvious that they're different.

sjanusz-r7 · 2026-07-02T15:41:25Z

Two things came up during testing:

Loading mcp plugin, calling mcp start results in Ctrl + C interrupt not working:

msf auxiliary(scanner/discovery/udp_sweep) > Interrupt: use the 'exit' command to quit
msf auxiliary(scanner/discovery/udp_sweep) > mcp start
[*] Auto-started msgrpc - User: msf, Pass: x
[*] MCP server listening on http://localhost:3000/
[*] Authentication: Bearer token (auto-generated)
[*]   Configure your MCP client with: Authorization: Bearer x
[*] Starting MCP server on HTTP transport...
msf auxiliary(scanner/discovery/udp_sweep) > // Ctrl + C does nothing here, even after calling `mcp stop`

I can start up the mcp daemon and the mcp plugin together, both report as listening:

## Tab 1
bundle exec ./msfmcpd --mcp-transport http
...
MCP server listening on http://localhost:3000/

## Tab 2
msf auxiliary(scanner/discovery/udp_sweep) > mcp start
[*] MCP server listening on http://localhost:3000/
[*] Authentication: Bearer token (auto-generated)
[*]   Configure your MCP client with: Authorization: Bearer x
[*] Starting MCP server on HTTP transport...

I expected the second tab to fail, as the address is already in use.

Otherwise, the bearer auth tests:

Default auto-generated token

// No token
curl http://localhost:3000/
{"error":"Unauthorized"}

// Correct token
curl -H "Authorization: Bearer foo" http://localhost:3000/
{"error":"Missing session ID"}

// Incorrect token
curl -H "Authorization: Bearer wrong_foo" http://localhost:3000/
{"error":"Unauthorized"}

Custom Token

Starting:

mcp start AuthToken='foo'
[*] MCP server listening on http://localhost:3000/
[*] Authentication: enabled
[*] Starting MCP server on HTTP transport...

Then:

// No token
curl http://localhost:3000/
{"error":"Unauthorized"}

// Correct token
curl -H "Authorization: Bearer foo" http://localhost:3000/
{"error":"Missing session ID"}

// Wrong token
curl -H "Authorization: Bearer wrong_foo" http://localhost:3000/
{"error":"Unauthorized"}

No auth token

Starting:

mcp start AuthToken=''
[*] MCP server listening on http://localhost:3000/
[*] Authentication: disabled
[*] Starting MCP server on HTTP transport...

Then:

// No token
curl http://localhost:3000/                               
{"error":"Missing session ID"}

// Any token provided
curl -H "Authorization: Bearer foo" http://localhost:3000/
{"error":"Missing session ID"}

zeroSteiner · 2026-07-06T17:29:10Z

I checked and both of these are pre-existing issues so I've opened dedicated tickets describing them in #21650 and #21649.

I should note that I wasn't able to reproduce the exact issue you noted with the dual bind, but it was definitely not correct, just in the way I described in the issue, not how you described it.

sjanusz-r7 · 2026-07-09T13:48:43Z

Unsure what about my environment is different, but I still didn't receive a bind error:

# Tab 1
Authenticating with Metasploit...
Authentication successful
Initializing MCP server...
Starting MCP server on HTTP transport...
MCP server listening on http://localhost:3000/
Authentication: Bearer token (auto-generated)
...

# Tab 2
msf auxiliary(scanner/discovery/udp_sweep) > load mcp
[*] MCP plugin loaded. Use mcp start to start the server.
[*] Successfully loaded plugin: mcp
msf auxiliary(scanner/discovery/udp_sweep) > mcp start
[*] Auto-started msgrpc - User: x, Pass: x
[*] Starting MCP server on HTTP transport...
[*] MCP server listening on http://localhost:3000/
[*] Authentication: Bearer token (auto-generated)
...

Apart from that, re-testing after latest changes:

Default token

-- No Token:
curl http://localhost:3000/ 
{"error":"Unauthorized"}

-- With correct token
curl -H "Authorization: Bearer foo" http://localhost:3000/
{"error":"Missing session ID"}

-- With incorrect token
curl -H "Authorization: Bearer bar" http://localhost:3000/
{"error":"Unauthorized"}

Custom token

-- No Token
curl http://localhost:3000/
{"error":"Unauthorized"}

-- Correct token
curl -H "Authorization: Bearer foo" http://localhost:3000/
{"error":"Missing session ID"}

-- Incorrect token
curl -H "Authorization: Bearer bar" http://localhost:3000/
{"error":"Unauthorized"}

No auth/token defined

[*] Authentication: disabled

-- No Token
curl http://localhost:3000/                               
{"error":"Missing session ID"}

-- Previously used token
curl -H "Authorization: Bearer foo" http://localhost:3000/
{"error":"Missing session ID"}

-- Previously unused, wrong token
curl -H "Authorization: Bearer bar" http://localhost:3000/
{"error":"Missing session ID"}

Working as expected.

CI also passed. Happy to land this once the final review from Christophe comes through 👍

zeroSteiner added 2 commits June 30, 2026 10:41

Suppress stack traces when the address is in use

002555e

Add authentication to the MCP plugin

558cc37

smcintyre-r7 added this to Metasploit Kanban Jun 30, 2026

github-project-automation Bot moved this to Todo in Metasploit Kanban Jun 30, 2026

zeroSteiner commented Jun 30, 2026

View reviewed changes

Update the specs

8c3f2e3

sjanusz-r7 self-assigned this Jul 2, 2026

This was referenced Jul 6, 2026

MCP Plugin Does Not Gracefully Handle Bind Failures #21649

Open

MCP Plugin Blocks Ctrl+C #21650

Open

cdelafuente-r7 reviewed Jul 7, 2026

View reviewed changes

Comment thread lib/msf/core/mcp/application.rb

Comment thread plugins/mcp.rb

Comment thread plugins/mcp.rb

Comment thread plugins/mcp.rb Outdated

Comment thread plugins/mcp.rb

cdelafuente-r7 added the rn-enhancement release notes enhancement label Jul 7, 2026

cdelafuente-r7 reviewed Jul 7, 2026

View reviewed changes

Comment thread plugins/mcp.rb Outdated

Comment thread plugins/mcp.rb Outdated

zeroSteiner added 4 commits July 7, 2026 15:09

Log bind failures too

cf55f30

Update the validator to process the auth token

0b877c3

Use a case insensitive key comparison

af86bf4

Add additional specs

7209a46

zeroSteiner requested a review from cdelafuente-r7 July 7, 2026 19:59

smcintyre-r7 moved this from Todo to Ready in Metasploit Kanban Jul 13, 2026

bwatters-r7 added this to the Version 6.5 milestone Jul 13, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add Bearer Authentication to the MCP server plugin#21622

Add Bearer Authentication to the MCP server plugin#21622
zeroSteiner wants to merge 7 commits into
rapid7:masterfrom
zeroSteiner:feat/mcp/plugin-auth

zeroSteiner commented Jun 30, 2026

Uh oh!

zeroSteiner Jun 30, 2026

Uh oh!

sjanusz-r7 commented Jul 2, 2026

Uh oh!

zeroSteiner commented Jul 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sjanusz-r7 commented Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

zeroSteiner commented Jun 30, 2026

Description

Breaking Changes

Reviewer Notes

Verification Steps

Test Evidence

Environment

AI Usage Disclosure

Pre-Submission Checklist

Uh oh!

zeroSteiner Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

sjanusz-r7 commented Jul 2, 2026

Default auto-generated token

Custom Token

No auth token

Uh oh!

zeroSteiner commented Jul 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sjanusz-r7 commented Jul 9, 2026

Default token

Custom token

No auth/token defined

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants