[orpiske]

Closes #2167

Summary

Adding an MCP server that requires authentication (for example the GitHub MCP server) through the admin UI, the management API, or the CLI failed with an opaque rmcp transport error. This change makes the failure clear and points to the fix.

• infra/src/mcp_client.rs: map HTTP 401 and 403 challenges from the rmcp transport to typed McpClientError::AuthRequired and McpClientError::InsufficientScope variants. All eight handshake sites use one connect_error helper.
• server/src/management/handlers.rs: create, refresh, and startup discovery build the status message in one place. When a forward without a discovery binding gets a 401, the message tells the operator to add a credential binding in wanaku.yaml.
• docs/credential-brokerage.md: add a GitHub MCP server example and a table of authentication status messages.

Status message before:

failed to connect to MCP server at http://127.0.0.1:8090/: Send message error Transport [rmcp::transport::worker::WorkerTransport<...>] error: Auth required, when send initialize request

After:

MCP server at http://127.0.0.1:8090/ requires authentication (HTTP 401). Add a credential binding for discovery to this forward in wanaku.yaml

Credential entry through the UI or the API is out of scope. That is #809, and it needs a security decision first (see #2167).

Testing

• New wiremock tests for 401, 403, and other handshake failures. New unit tests for the status-message hint.
• cargo test -p wanaku-infra mcp_client and cargo test -p wanaku-server forward_helpers_tests pass.
• cargo clippy --workspace --all-targets adds no warnings compared with main.
• Manual test against github-mcp-server v2.0.2 in http mode. Without a binding, the forward shows the new message. With a wanaku.yaml bearer binding, discovery finds 46 tools, 9 resources, and 2 prompts, and tools/call works through /<namespace>/mcp.

---

Generated by Claude Code

Summary by Sourcery

Report actionable upstream authentication failures during MCP forward discovery and guide operators to configure the required credential bindings.

New Features:

• Provide clear authentication status messages for MCP forward discovery failures, including guidance when a discovery credential binding is missing.
• Document configuring a GitHub MCP server with credential bindings and troubleshooting authentication failures.

Bug Fixes:

• Translate upstream HTTP 401 and insufficient-scope HTTP 403 handshake failures into actionable typed MCP client errors instead of opaque transport errors.

Enhancements:

• Centralize discovery failure status-message construction across forward creation, refresh, and startup discovery while preserving credential redaction.

Documentation:

• Add a GitHub MCP server credential-brokerage example and an authentication troubleshooting status table.

Tests:

• Add coverage for HTTP 401, HTTP 403 insufficient-scope, other handshake failures, and discovery-binding status hints.

[sourcery-ai]

Sorry @orpiske, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 3 hours and 7 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

The PR replaces opaque rmcp handshake failures with typed 401/403 errors, propagates them into consistent and actionable forward discovery status messages, and documents GitHub MCP authentication configuration and troubleshooting.

Flow diagram for configuring authenticated MCP discovery

flowchart LR
    Token[Create GitHub personal access token]
    Env[Set GITHUB_PAT]
    Binding[Add discovery credential binding in wanaku.yaml]
    Discover[Forward discovery]
    Tools[Discover tools resources and prompts]
    Failure[Show actionable authentication status]

    Token --> Env --> Binding --> Discover
    Discover -->|Credential accepted| Tools
    Discover -->|401 without binding| Failure
    Discover -->|401 with rejected credential| Failure
    Discover -->|403 insufficient scope| Failure

Loading

File-Level Changes

Change	Details	Files
Translate upstream HTTP authentication failures into actionable typed MCP client errors.	Added typed errors for HTTP 401 authentication requirements and HTTP 403 insufficient scope. Centralized handshake error mapping across all MCP client connection sites. Added wiremock coverage for authentication, authorization, and non-authentication handshake failures.	infra/src/mcp_client.rs
Generate consistent, actionable discovery status messages across forward lifecycle operations.	Centralized failure-message construction for create, refresh, and startup discovery. Added a wanaku.yaml credential-binding hint when an unauthenticated forward lacks a discovery binding. Preserved credential redaction and added tests for bound and unbound forwards.	server/src/management/handlers.rs
Document credential setup and troubleshooting for authenticated MCP discovery.	Added a GitHub MCP server bearer-token configuration example. Documented authentication status messages, causes, and remediation steps. Clarified that UI/API credential entry is not supported by this change.	docs/credential-brokerage.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#2167	Report upstream HTTP 401 and 403 responses during MCP handshake as typed authentication errors rather than opaque transport failures.	✅
#2167	Show forward operators a clear authentication failure status, including a wanaku.yaml discovery-binding hint when no discovery binding is configured.	✅
#2167	Document how to configure credential binding for a GitHub MCP server.	✅

Possibly linked issues

• Report authentication failures clearly when forward discovery gets HTTP 401/403 #2167: The PR implements the issue’s proposed typed 401/403 errors, actionable discovery status messages, and GitHub credential-brokerage documentation.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[wanaku-integration-tests]

Integration Test Results

Run: https://github.com/wanaku-ai/wanaku-tests/actions/runs/39411161924
Wanaku: wanaku-ai/wanaku @ claude/wanaku-github-mcp-compat-6s4azf

Test Results

Module	Tests	Passed	Failed	Errors	Skipped	Time
camel-integration-capability-tests	-	-	-	-	-	-
semantic-router-tests	-	-	-	-	-	-
a2a-tests	-	-	-	-	-	-
resources-tests	-	-	-	-	-	-
router-tests	-	-	-	-	-	-
mcp-forwarding-tests	-	-	-	-	-	-
governance-tests	-	-	-	-	-	-
Total	0	0	0	0	0	0s