Documentation/error improvement request on running with bearer token

[nettrino]

Hello and thanks for putting together this tool! I am trying to run the fuzzer against a local server requiring a bearer token and was not able to figure this out from the current docs originally:

Wrt to running with a config.yaml:

 python3 -m mcp_fuzzer --config config.yaml --server localhttp

getting error: unrecognized arguments: --server localhttp

When creating the following config

mode: "tools"
protocol: http
endpoint: "http://localhost:8080/mcp"
runs: 10
phase: "aggressive"
timeout: 30.0
log_level: "INFO"
safety_enabled: true
max_concurrency: 5
phase: both
auth:
  type: oauth
  token: "xxx"
  header_name: "Authorization"

as per this doc I get

mcp-fuzzer ❯ python3 -m mcp_fuzzer --config config.yaml
Error: --endpoint is required for fuzzing operations

I also tried to follow the instructions on

export MCP_API_KEY=xxx
export MCP_TOOL_AUTH_MAPPING='{"secure_tool":"api_key"}'
python3 -m mcp_fuzzer --mode tools --protocol http --endpoint http://localhost:8080/mcp --runs 2 --timeout 5 --auth-env

trying to pass in my API key but getting HTTP 401: no bearer token.

I've also tried using python3 -m mcp_fuzzer --mode tools --protocol http --endpoint http://localhost:8080/mcp --runs 2 --timeout 5 --auth-config auth_config.json with

{
  "providers": {
    "api_key": {
      "type": "oauth",
      "token": "xxx"
    }
  },
  "tool_mappings": {
    "secure_tool": "api_key"
  }
}

as well as

{
  "providers": {
    "api_key": {
      "type": "api_key",
      "api_key": "xxx",
      "header_name": "Authorization",
      "prefix": "Bearer"
    }
  },
  "tool_mappings": {
    "secure_tool": "api_key"
  }
}

But getting 401 still.

Had also tried

{
  "providers": {
    "oauth": {
      "type": "oauth",
      "token": "xxx"
    }
  },
  "tool_mappings": {
    "secure_tool": "oauth"
  }
}

Btw, this is a golang mcp server, and I also tried STDIO as follows

mcp-fuzzer ❯ mcp-fuzzer --mode tools --protocol stdio --endpoint "go run /<path_to_my_main.go>" --runs 10 --enable-safety-system
MCP Fuzzer - TOOLS Mode
Protocol: STDIO
Endpoint: go run <path_to_my_main.go>
2025-11-04 11:38:53,546 - root - ERROR - Failed to fetch tools from server: No response received from stdio transport
Traceback (most recent call last):
  File "/Users/nettrino/tools/mcp-server-fuzzer/mcp_fuzzer/transport/base.py", line 60, in get_tools
    response = await self.send_request("tools/list")
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nettrino/tools/mcp-server-fuzzer/mcp_fuzzer/transport/stdio.py", line 199, in send_request
    raise Exception("No response received from stdio transport")
Exception: No response received from stdio transport
2025-11-04 11:38:53,548 - mcp_fuzzer.client.tool_client - WARNING - Server returned an empty list of tools.

Another nice to have would be some better error reporting in case of a bad json passed - currently getting Unexpected error: 'api_key' and similar, which does not inform the user what the required/expected values are.

[nettrino]

A sample working curl command for my server is

curl -H 'Authorization: Bearer xxx' \
     -H 'Content-Type: application/json' \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "initialize",
       "params": {
         "protocolVersion": "2024-11-05",
         "capabilities": {},
         "clientInfo": {
           "name": "test-client",
           "version": "1.0.0"
         }
       }
     }' \
     http://localhost:8080/mcp

[Agent-Hellboy]

@nettrino , sorry for the late reply. Do you want to add a PR with the fix or else i will debug this week?

[Agent-Hellboy]

Hi @nettrino , I have tested per tool auth only, that too before major refactoring, and btw it's tool_mapping not tools_mappings , anyways it will still fail.

[Agent-Hellboy]

Hi @nettrino , I have added a PR, Please help test it.

About Stdio transport please run it from this PR, I think it would , you might be running the older version of the tool.

[Agent-Hellboy]

released new version , please check

[nettrino]

thanks for getting to this and apologies for the late reply will get back to you on this today/tmr after checking!

[nettrino]

@Agent-Hellboy I tested again with the latest from main and using the following auth_config

{
  "default_provider": "api_key",
  "providers": {
    "api_key": {
      "type": "api_key",
      "header_name": "Authorization",
      "prefix": "Bearer",
      "api_key": "xxx"
    }
  },
  "tool_mapping": {
    "secure_tool": "api_key"
  }
}

I get

mcp-fuzzer ❯ python3 -m mcp_fuzzer --mode tools --protocol http --endpoint http://localhost:8080/mcp --runs 2 --timeout 5 --auth-config auth_config.json
MCP Fuzzer - TOOLS Mode
Protocol: HTTP
Endpoint: http://localhost:8080/mcp
2025-11-24 11:10:11,164 - root - INFO - Client received config with export flags: csv=None, xml=None, html=None, md=None
2025-11-24 11:10:11,166 - root - INFO - Filesystem sandbox initialized at: /Users/nettrino/.mcp_fuzzer
2025-11-24 11:10:11,166 - root - INFO - Filesystem sandbox initialized at: /Users/nettrino/.mcp_fuzzer
2025-11-24 11:10:11,166 - root - INFO - FuzzerReporter initialized with output directory: reports
2025-11-24 11:10:11,166 - mcp_fuzzer.client.tool_client - INFO - Starting Two-Phase Tool Fuzzing
2025-11-24 11:10:11,207 - httpx - INFO - HTTP Request: POST http://localhost:8080/mcp "HTTP/1.1 401 Unauthorized"
2025-11-24 11:10:11,207 - HTTPTransport - ERROR - HTTP 401: no bearer token

2025-11-24 11:10:11,207 - root - ERROR - Failed to fetch tools from server: HTTP 401: no bearer token
Traceback (most recent call last):
  File "/Users/nettrino/tools/mcp-server-fuzzer/mcp_fuzzer/transport/mixins.py", line 316, in _handle_http_response_error
    response.raise_for_status()
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/Users/nettrino/venvs/mcp-fuzzer/lib/python3.13/site-packages/httpx/_models.py", line 829, in raise_for_status
    raise HTTPStatusError(message, request=request, response=self)
httpx.HTTPStatusError: Client error '401 Unauthorized' for url 'http://localhost:8080/mcp'
For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/nettrino/tools/mcp-server-fuzzer/mcp_fuzzer/transport/base.py", line 56, in get_tools
    response = await self.send_request("tools/list")
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nettrino/tools/mcp-server-fuzzer/mcp_fuzzer/transport/http.py", line 134, in send_request
    self._handle_http_response_error(response)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^
  File "/Users/nettrino/tools/mcp-server-fuzzer/mcp_fuzzer/transport/mixins.py", line 320, in _handle_http_response_error
    raise NetworkError(error_msg)
mcp_fuzzer.transport.mixins.NetworkError: HTTP 401: no bearer token

2025-11-24 11:10:11,209 - mcp_fuzzer.client.tool_client - WARNING - Server returned an empty list of tools.
2025-11-24 11:10:11,209 - mcp_fuzzer.client.tool_client - WARNING - No tools available for fuzzing
2025-11-24 11:10:11,209 - mcp_fuzzer.reports.output.protocol - INFO - Output saved to: reports/sessions/04d8e7e7-95aa-4c54-9df9-df753e0527ed/20251124_111011_fuzzing_results.json
2025-11-24 11:10:11,209 - root - INFO - Generated standardized reports: ['fuzzing_results']
2025-11-24 11:10:11,209 - root - INFO - Checking export flags: csv=None, xml=None, html=None, md=None
2025-11-24 11:10:11,209 - root - INFO - Client reporter available: True
2025-11-24 11:10:11,209 - mcp_fuzzer.fuzz_engine.runtime.manager - INFO - Shutting down process manager
2025-11-24 11:10:11,209 - mcp_fuzzer.fuzz_engine.runtime.manager - INFO - Process manager shutdown complete

[Agent-Hellboy]

@nettrino sorry man, it's because of header sanitization, which is discarding the Authorization, I will fix it, and will add an e2e test with auth flow.