rework of authentication with additional features and capabilities

Author: vparla

CMakeLists.txt

@@ -51,6 +51,7 @@ add_library(mcp_cpp STATIC
     src/mcp/Server.cpp
     src/mcp/auth/OAuthClient.cpp
     src/mcp/auth/OAuth2ClientCredentialsAuth.cpp
+    src/mcp/auth/WwwAuthenticate.cpp
     src/mcp/auth/ServerAuth.cpp
     src/mcp/JsonRpcMessageRouter.cpp
     src/mcp/ContentLengthFramer.cpp

Dockerfile.demo

@@ -40,6 +40,7 @@ RUN bash -lc 'set -euo pipefail; \
 FROM build AS test
 ARG MCP_STDIOTRANSPORT_TIMEOUT_MS
 ENV MCP_STDIOTRANSPORT_TIMEOUT_MS=${MCP_STDIOTRANSPORT_TIMEOUT_MS}
+ENV MCP_IN_CONTAINER=1
 ENV GTEST_COLOR=yes
 ENV CTEST_OUTPUT_ON_FAILURE=1
 WORKDIR /src

docs/api/server.md

@@ -27,6 +27,15 @@ In this SDK the server and/or client use the experimental map for:
 - `capabilities.experimental.logLevel` (client → server) — see [Logging to client](#logging-to-client) for client-selected minimum log level.
 - `capabilities.experimental.resourceReadChunking` (server → client) — see [Resource read chunking (experimental)](#resource-read-chunking-experimental).
 
+## Extensions capabilities (optional)
+
+Clients may advertise optional extensions in the initialize request under `capabilities.extensions` (per SEP‑1724). The SDK now models these verbatim in `ClientCapabilities.extensions` so server code can detect extension support without schema loss. For MCP Apps (SEP‑1865), the extension identifier is `io.modelcontextprotocol/ui` (see `Extensions::uiExtensionId` in [include/mcp/Protocol.h](../../include/mcp/Protocol.h)).
+
+Notes:
+
+- Unknown extension objects are preserved as `JSONValue`s without interpretation.
+- Malformed shapes (non‑object `extensions`, wrong types inside entries) are ignored safely during parsing.
+
 ## Type aliases and handlers
 - using ToolResult = CallToolResult
 - using ResourceContent = ReadResourceResult
@@ -231,6 +240,29 @@ acceptor->Start().get();
 - std::vector<Tool> ListTools()
 - std::future<JSONValue> CallTool(const std::string& name, const JSONValue& arguments)
 
+### Tools metadata (`_meta`)
+
+- The `Tool` type supports an optional metadata field serialized as `_meta` in `tools/list` responses. This allows servers to attach arbitrary JSON metadata to tools without changing the core schema.
+- Example: Linking a tool to a UI resource (MCP Apps):
+
+```json
+{
+  "tools": [
+    {
+      "name": "get_weather",
+      "description": "Get weather with interactive dashboard",
+      "inputSchema": { "type": "object", "properties": { "location": {"type":"string"} } },
+      "_meta": { "ui/resourceUri": "ui://weather-server/dashboard" }
+    }
+  ]
+}
+```
+
+Notes:
+
+- `_meta` is omitted when not provided.
+- The value is a free-form JSON object (or any JSONValue preserved verbatim). Hosts that do not recognize `_meta` safely ignore it.
+
 ## Resources
 - void RegisterResource(const std::string& uri, ResourceHandler handler)
 - void UnregisterResource(const std::string& uri)

examples/logging_demo/main.cpp

@@ -32,25 +32,28 @@ int main() {
     auto client = factory.CreateClient(info);
     client->Connect(std::move(clientTrans)).get();
 
-    // Capture log notifications on client
+    // Capture log notifications (notifications/message): level + data
     client->SetNotificationHandler(Methods::Log, [&](const std::string& method, const JSONValue& params){
         (void)method;
         if (std::holds_alternative<JSONValue::Object>(params.value)) {
             const auto& o = std::get<JSONValue::Object>(params.value);
             auto itLvl = o.find("level");
-            auto itMsg = o.find("message");
-            if (itLvl != o.end() && itMsg != o.end() &&
-                std::holds_alternative<std::string>(itLvl->second->value) &&
-                std::holds_alternative<std::string>(itMsg->second->value)) {
-                std::cout << "log [" << std::get<std::string>(itLvl->second->value) << "]: "
-                          << std::get<std::string>(itMsg->second->value) << "\n";
+            auto itData = o.find("data");
+            if (itLvl != o.end() && itData != o.end() &&
+                std::holds_alternative<std::string>(itLvl->second->value)) {
+                std::cout << "log [" << std::get<std::string>(itLvl->second->value) << "]: ";
+                if (std::holds_alternative<std::string>(itData->second->value)) {
+                    std::cout << std::get<std::string>(itData->second->value);
+                } else {
+                    std::cout << "(non-string payload)";
+                }
+                std::cout << "\n";
             }
         }
     });
 
-    // Initialize with client min log level WARN
-    ClientCapabilities caps; caps.experimental["logLevel"] = JSONValue{std::string("WARN")};
-    (void)client->Initialize(info, caps).get();
+    // Initialize client
+    ClientCapabilities caps; (void)client->Initialize(info, caps).get();
 
     // INFO should be suppressed, ERROR delivered
     server.LogToClient("INFO", "info suppressed", std::nullopt);

include/mcp/HTTPTransport.hpp

@@ -12,6 +12,8 @@
 #include <future>
 #include <atomic>
 #include <functional>
+#include <optional>
+#include <vector>
 
 #include "mcp/Transport.h"
 #include "mcp/auth/IAuth.hpp"
@@ -24,6 +26,17 @@ namespace mcp {
 //==========================================================================================================
 class HTTPTransport : public ITransport {
 public:
+    //==========================================================================================================
+    // HttpResponseInfo
+    // Purpose: Exposes HTTP status and headers from the last completed HTTP request. Used for auth discovery
+    //          (e.g., parsing WWW-Authenticate on 401/403).
+    //==========================================================================================================
+    struct HttpResponseInfo {
+        int status{0};
+        std::vector<mcp::auth::HeaderKV> headers;
+        std::string wwwAuthenticate; // convenience copy of WWW-Authenticate if present
+    };
+    
     //==========================================================================================================
     // Options
     // Purpose: Configuration for HTTP/HTTPS endpoints and TLS verification.
@@ -115,6 +128,13 @@ class HTTPTransport : public ITransport {
     void SetAuth(mcp::auth::IAuth& auth);
     void SetAuth(std::shared_ptr<mcp::auth::IAuth> auth);
 
+    //==========================================================================================================
+    // TryGetLastHttpResponse
+    // Purpose: Copies the last observed HTTP response info (if any). Returns true on success.
+    //          Thread-safe; returns a snapshot and does not clear the stored value.
+    //==========================================================================================================
+    bool QueryLastHttpResponse(HttpResponseInfo& out) const;
+
 private:
     class Impl;
     std::unique_ptr<Impl> pImpl;

include/mcp/Protocol.h

@@ -20,7 +20,13 @@ namespace mcp {
 //==========================================================================================================
 ///////////////////////////////////////// Protocol constants ///////////////////////////////////////////
 // MCP Protocol version
-constexpr const char* PROTOCOL_VERSION = "2025-06-18";
+constexpr const char* PROTOCOL_VERSION = "2025-11-25";
+
+// MCP Extensions identifiers (optional capability negotiation)
+namespace Extensions {
+    // UI apps extension identifier (SEP-1865)
+    constexpr const char* uiExtensionId = "io.modelcontextprotocol/ui";
+}
 
 ///////////////////////////////////////// Implementation ///////////////////////////////////////////
 // Implementation information
@@ -70,6 +76,8 @@ struct ServerCapabilities {
 struct ClientCapabilities {
     std::optional<SamplingCapability> sampling;
     std::unordered_map<std::string, JSONValue> experimental;
+    // Optional negotiated extensions per SEP-1724 (e.g., io.modelcontextprotocol/ui)
+    std::unordered_map<std::string, JSONValue> extensions;
 };
 
 ///////////////////////////////////////// Tools ///////////////////////////////////////////
@@ -78,10 +86,13 @@ struct Tool {
     std::string name;
     std::string description;
     JSONValue inputSchema;  // JSON Schema for tool parameters
+    std::optional<JSONValue> meta; // serialized as _meta in tools/list
 
     Tool() = default;
-    Tool(std::string name, std::string description, JSONValue inputSchema = JSONValue{})
-        : name(std::move(name)), description(std::move(description)), inputSchema(std::move(inputSchema)) {}
+    Tool(std::string name, std::string description, JSONValue inputSchema = JSONValue{},
+         std::optional<JSONValue> metaValue = std::nullopt)
+        : name(std::move(name)), description(std::move(description)),
+          inputSchema(std::move(inputSchema)), meta(std::move(metaValue)) {}
 };
 
 struct CallToolParams {
@@ -234,6 +245,7 @@ namespace Methods {
     constexpr const char* ReadResource = "resources/read";
     constexpr const char* Subscribe = "resources/subscribe";
     constexpr const char* Unsubscribe = "resources/unsubscribe";
+    constexpr const char* SetLogLevel = "logging/setLevel";
     constexpr const char* ListResourceTemplates = "resources/templates/list";
     constexpr const char* ListPrompts = "prompts/list";
     constexpr const char* GetPrompt = "prompts/get";
@@ -245,7 +257,7 @@ namespace Methods {
     constexpr const char* Initialized = "notifications/initialized";
     constexpr const char* Progress = "notifications/progress";
     constexpr const char* Keepalive = "notifications/keepalive";
-    constexpr const char* Log = "notifications/log";
+    constexpr const char* Log = "notifications/message";
     constexpr const char* ResourceListChanged = "notifications/resources/list_changed";
     constexpr const char* ToolListChanged = "notifications/tools/list_changed";
     constexpr const char* PromptListChanged = "notifications/prompts/list_changed";

include/mcp/auth/WwwAuthenticate.hpp

@@ -0,0 +1,34 @@
+//==========================================================================================================
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 Vinny Parla
+// File: WwwAuthenticate.hpp
+// Purpose: Parser for HTTP WWW-Authenticate Bearer challenges (RFC 6750/RFC 9728 parameters)
+//==========================================================================================================
+
+#pragma once
+
+#include <string>
+#include <unordered_map>
+
+namespace mcp::auth {
+
+//==========================================================================================================
+// WwwAuthChallenge
+// Purpose: Parsed representation of a single WWW-Authenticate challenge line.
+//==========================================================================================================
+struct WwwAuthChallenge {
+    std::string scheme;                                          // e.g., "Bearer" (canonicalized as lower-case)
+    std::unordered_map<std::string, std::string> params;         // key -> value (unquoted, unescaped)
+};
+
+//==========================================================================================================
+// parseWwwAuthenticate
+// Purpose: Parse a single WWW-Authenticate header value. Supports Bearer scheme with comma-separated
+//          key=value parameters (values may be quoted). Returns true on successful parse of Bearer scheme.
+// Notes:
+//   - Returns false for unsupported schemes (e.g., Basic), or malformed inputs.
+//   - Keys are case-sensitive as transmitted; scheme is returned lower-case.
+//==========================================================================================================
+bool parseWwwAuthenticate(const std::string& header, WwwAuthChallenge& out);
+
+} // namespace mcp::auth

scripts/ci_all.sh

@@ -34,6 +34,7 @@ echo "[ci_all] 1b/3 List discovered unit/integration tests"
 docker run --rm \
   -e GTEST_COLOR=yes \
   -e CTEST_OUTPUT_ON_FAILURE=1 \
+  -e MCP_IN_CONTAINER=1 \
   --ipc=host \
   mcp-cpp-build \
   ctest --test-dir build -N -V
@@ -43,6 +44,7 @@ echo "[ci_all] 1c/3 Run unit/integration tests verbosely"
 docker run --rm \
   -e GTEST_COLOR=yes \
   -e CTEST_OUTPUT_ON_FAILURE=1 \
+  -e MCP_IN_CONTAINER=1 \
   --ipc=host \
   mcp-cpp-build \
   ctest --test-dir build -VV --progress
@@ -64,3 +66,4 @@ chmod +x scripts/http_e2e.sh scripts/http_down.sh
 ./scripts/http_down.sh || true
 
 echo "[ci_all] SUCCESS: All tests passed"
+

src/mcp/HTTPTransport.cpp

@@ -69,6 +69,10 @@ class HTTPTransport::Impl {
     std::shared_ptr<mcp::auth::IAuth> authStrong;
     mcp::auth::IAuth* authWeak{nullptr};
 
+    // Snapshot of the last HTTP response (status + headers) for auth discovery
+    mutable std::mutex lastRespMutex;
+    HTTPTransport::HttpResponseInfo lastResp;
+
     explicit Impl(const HTTPTransport::Options& o) : opts(o) {
         // Random session id similar to InMemoryTransport
         std::random_device rd; std::mt19937 gen(rd()); std::uniform_int_distribution<> dis(1000, 9999);
@@ -131,6 +135,25 @@ class HTTPTransport::Impl {
         }
     }
 
+    void recordResponse(const http::response<http::string_body>& res) {
+        HTTPTransport::HttpResponseInfo info;
+        info.status = static_cast<int>(res.result_int());
+        for (const auto& h : res.base()) {
+            mcp::auth::HeaderKV kv;
+            kv.name = std::string(h.name_string());
+            kv.value = std::string(h.value());
+            info.headers.push_back(std::move(kv));
+        }
+        auto const& wa = res[http::field::www_authenticate];
+        if (!wa.empty()) {
+            info.wwwAuthenticate = std::string(wa);
+        }
+        {
+            std::lock_guard<std::mutex> lk(lastRespMutex);
+            lastResp = std::move(info);
+        }
+    }
+
     void setError(const std::string& msg) {
         if (errorHandler) {
             errorHandler(msg);
@@ -229,6 +252,7 @@ class HTTPTransport::Impl {
                 if (errorHandler) {
                     errorHandler(std::string("HTTP DEBUG: https status=") + std::to_string(res.result_int()) + std::string(" content-type=") + std::string(res[http::field::content_type]));
                 }
+                recordResponse(res);
                 boost::system::error_code ec; stream.shutdown(ec);
                 co_return res.body();
             } else {
@@ -277,6 +301,7 @@ class HTTPTransport::Impl {
                 if (errorHandler) {
                     errorHandler(std::string("HTTP DEBUG: http status=") + std::to_string(res.result_int()) + std::string(" content-type=") + std::string(res[http::field::content_type]));
                 }
+                recordResponse(res);
                 boost::system::error_code ec; stream.socket().shutdown(tcp::socket::shutdown_both, ec);
                 co_return res.body();
             }
@@ -606,6 +631,29 @@ void HTTPTransport::SetAuth(std::shared_ptr<mcp::auth::IAuth> auth) {
     }
 }
 
+bool HTTPTransport::QueryLastHttpResponse(HttpResponseInfo& out) const {
+    FUNC_SCOPE();
+    // Rationale: return true as soon as ANY meaningful part of the last HTTP response snapshot
+    // is available (OR semantics), rather than requiring ALL fields (AND semantics).
+    // - Real responses may legitimately omit fields (e.g., 200 OK has no WWW-Authenticate).
+    // - We record status/headers opportunistically; OR semantics avoids false negatives and remains
+    //   resilient if future changes only capture a subset (e.g., headers or a challenge line).
+    {
+        std::lock_guard<std::mutex> lk(pImpl->lastRespMutex);
+        out = pImpl->lastResp;
+    }
+    if (out.status != 0) {
+        return true;
+    }
+    if (!out.headers.empty()) {
+        return true;
+    }
+    if (!out.wwwAuthenticate.empty()) {
+        return true;
+    }
+    return false;
+}
+
 //==========================================================================================================
 // HTTPTransportFactory::CreateTransport
 // Purpose: Parse semicolon-delimited key=value config into Options and create transport.

src/mcp/InMemoryTransport.cpp

@@ -80,17 +80,20 @@ class InMemoryTransport::Impl {
     void processMessage(const std::string& message) {
         LOG_DEBUG("Processing in-memory message: {}", message);
 
-        // First, handle responses (have top-level result or error)
-        if (message.find("\"result\"") != std::string::npos || message.find("\"error\"") != std::string::npos) {
+        // Classify the message using the router to avoid false positives on nested keys/values.
+        auto kind = router ? router->classify(message) : IJsonRpcMessageRouter::MessageKind::Unknown;
+
+        // Handle responses (top-level result or error)
+        if (kind == IJsonRpcMessageRouter::MessageKind::Response) {
             JSONRPCResponse response;
             if (response.Deserialize(message)) {
                 handleResponse(std::move(response));
                 return;
             }
         }
-        // Next, handle requests: must have a method and a TOP-LEVEL id
-        if (message.find("\"method\"") != std::string::npos && router &&
-            router->classify(message) == IJsonRpcMessageRouter::MessageKind::Request) {
+
+        // Handle requests (must have method and top-level id)
+        if (kind == IJsonRpcMessageRouter::MessageKind::Request) {
             JSONRPCRequest request;
             if (request.Deserialize(message)) {
                 if (requestHandler) {
@@ -119,7 +122,8 @@ class InMemoryTransport::Impl {
                 }
             }
         }
-        // Finally, treat as notification
+
+        // Finally, notification
         {
             JSONRPCNotification notification;
             if (notification.Deserialize(message)) {