Add a blog post about secure MCP SSE server

Author: sberyozkin

_posts/2025-04-23-secure-mcp-sse-server.adoc

@@ -0,0 +1,205 @@
+---
+layout: post
+title: 'Getting ready for secure MCP with Quarkus MCP Server'
+date: 2025-04-23
+tags: ai mcp security
+synopsis: 'Demonstrate secure Quarkus MCP SSE server access in dev mode'
+author: sberyozkin
+---
+:imagesdir: /assets/images/posts/secure_mcp_sse_server
+
+== Introduction
+
+https://modelcontextprotocol.io/specification/2025-03-26[The latest version of the Model Context Protocol (MCP) specification] introduces an https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization[authorization] flow for HTTP based MCP transports.
+
+MCP authorization enables MCP SSE and Streamable HTTP clients to access MCP servers securely and is being very actively discussed and evaluated right now. This https://github.com/modelcontextprotocol/modelcontextprotocol/pull/284[MCP authorization PR] is one of the focal points for the MCP authorization discussions.
+
+While it will take a bit of time for the MCP authorization specification be finalized and widely supported, one thing you can be certain about is that secure MCP servers that wish to interoperate with MCP authorization aware MCP clients will be required to accept and verify bearer access tokens sent by these clients on behalf of their users.
+
+The https://github.com/quarkiverse/quarkus-mcp-server[Quarkus MCP Server project] is ready for you to start experimenting with secure MCP SSE servers.
+
+In this post, we will show how Quarkus provides a complete Dev UI experience for you to login with an OpenId Connect or OAuth2 provider of your choice, and use an acquired access token to access MCP SSE server securely.
+
+== Create MCP SSE server
+
+First, let's create a secure Quarkus MCP SSE server.
+
+You can find the complete project source https://github.com/quarkiverse/quarkus-mcp-server/tree/main/samples/secure-mcp-sse-server[here].
+
+=== Maven dependencies
+
+Add the following dependencies:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.quarkiverse.mcp</groupId>
+    <artifactId>quarkus-mcp-server-sse</artifactId> <1>
+    <version>1.1.1</version>
+</dependency>
+
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-oidc</artifactId> <2>
+</dependency>
+----
+<1> `quarkus-mcp-server-sse` is required to support the MCP SSE transport.
+<2> `quarkus-oidc` is required to secure access to the MCP SSE endpoints.
+
+[[tool]]
+=== Tool
+
+Let's create a tool that can be invoked only if the current MCP request is authenticated:
+
+[source,java]
+----
+package org.acme;
+
+import io.quarkiverse.mcp.server.TextContent;
+import io.quarkiverse.mcp.server.Tool;
+import io.quarkus.security.Authenticated;
+import io.quarkus.security.identity.SecurityIdentity;
+import jakarta.inject.Inject;
+
+public class ServerFeatures {
+
+    @Inject
+    SecurityIdentity identity;
+
+    @Tool(name = "user-name-provider", description = "Provides a name of the current user") <1>
+    @Authenticated <2>
+    TextContent provideUserName() {
+        return new TextContent(identity.getPrincipal().getName()); <3>
+    }
+}
+----
+<1> Provide a tool that can return a name of the current user. Note the `user-name-provider` tool name, you will use it later for a tool call.
+<2> Require authenticated tool access. See also how the main MCP SSE endpoint is secured in the <<configuration>> section below.
+<3> Use the injected `SecurityIdentity` to return the current user's name.
+
+[[configuration]]
+=== Configuration
+
+Finally, let's configure our secure MCP server:
+
+[source,properties]
+----
+quarkus.http.auth.permission.authenticated.paths=/mcp/sse
+quarkus.http.auth.permission.authenticated.policy=authenticated
+----
+<1> Enforce an authenticated access to the main MCP SSE endpoint. See also how the tool is secured with an annotation in the <<tool>> section above, though you can also secure access to the tool by listing both the main and tools endpoints in the configuration, for example: `quarkus.http.auth.permission.authenticated.paths=/mcp/sse,/mcp/messages/*`.
+
+The OIDC configuration is provided in devmode by https://quarkus.io/guides/security-openid-connect-dev-services[Dev Services for Keycloak]. It creates a default realm, client and adds two users, `alice` and `bob`, for you to get started immediately. You can also register a custom Keycloak realm to work with the the existing realm, client and user registrations.
+
+No problems if you do not work with Keycloak, see the <<mcp-server-devui>> section for more details.
+
+We are ready to test our secure MCP server, both in DevUI and with `curl`.
+
+== Start MCP SSE server
+
+Start the server in the dev mode:
+
+[source,shell]
+----
+mvn quarkus:dev
+----
+
+[[mcp-server-devui]]
+=== Access MCP SSE server in DevUI
+
+Go to http://localhost:8080/q/dev[Dev UI], find both MCP Server and OpenId Connect cards:
+
+image::mcp_server_oidc_devui.png[MCP Server and OIDC in DevUI,align="center"]
+
+Select an OpenId Connect card and https://quarkus.io/guides/security-openid-connect-dev-services#develop-service-applications[login to Keycloak] using an `alice` name and an `alice` password.
+
+What about other providers such as `Auth0` or https://quarkus.io/guides/security-openid-connect-providers#github[GitHub] ?
+In this case, you can login to them from OIDC DevUI as well, the only requirement is to update your provider application registration to allow callbacks to DevUI. For example, see how you can https://quarkus.io/guides/security-oidc-auth0-tutorial#looking-at-auth0-tokens-in-the-oidc-dev-ui[login to Auth0].
+
+After logging in with `Keycloak` as `alice`, copy the acquired access token using a provided copy button:
+
+image::login_and_copy_access_token.png[Login and copy access token,align="center"]
+
+Now go the MCP Server card, select the `Tools` option and choose the `user-name-provider` tool:
+
+image::mcp_server_choose_tool.png[Choose MCP Server tool,align="center"]
+
+Paste the copied access token into the Tool's `Bearer token` field, and request a new MCP SSE session:
+
+image::mcp_server_bearer_token.png[MCP Server Bearer token,align="center"]
+
+Make a tool call by selecting the `Call` action and get a response which contains the `alice` user name:
+
+image::mcp_server_tool_response.png[MCP Server tool response,align="center"]
+
+=== Access MCP SSE server with curl
+
+Let's try to use `curl` as well and also learn a little bit how MCP SSE transport works. 
+
+Access the main SSE endpoint without the access token first:
+
+[source,shell]
+----
+curl -v localhost:8080/mcp/sse
+----
+
+You will get HTTP 401 error.
+
+Next, get and copy the access token as explained in the <<mcp-server-devui>> section above. You can use the same access token that you may have already used when working through that section.
+
+[source,shell]
+----
+curl -v -H "Authorization: Bearer ey..." localhost:8080/mcp/sse
+----
+
+and get an SSE response such as:
+
+[source,shell]
+----
+< content-type: text/event-stream
+< 
+event: endpoint
+data: /messages/ZTZjZDE5MzItZDE1ZC00NzBjLTk0ZmYtYThiYTgwNzI1MGJ
+----
+
+The current `curl` SSE session must stay open, for it to receive updates related to the dynamically allocated `data` endpoint.
+
+Open another window and use the same access token to post the tool call request to the `data` endpoint:
+
+[source,shell]
+----
+url -v -H "Authorization: Bearer ey..." -H "Content-Type: application/json" --data @call.json http://localhost:8080/mcp/messages/ZTZjZDE5MzItZDE1ZC00NzBjLTk0ZmYtYThiYTgwNzI1MGJ
+----
+
+where a `call.json` looks like this:
+
+[source,json]
+----
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "user-name-provider",
+    "arguments": {
+    }
+  }
+}
+----
+
+Now look in the first curl window and observe a response such as:
+
+[source,shell]
+----
+event: message
+data: {"jsonrpc":"2.0","id":2,"result":{"isError":false,"content":[{"text":"alice","type":"text"}]}}
+----
+
+== Conclusion
+
+In the this blog post, we have explained how a secure Quarkus MCP SSE server can be created and tested in Quarkus Dev UI and with the `curl` tool.
+Please give it a try as well.
+
+The Quarkus team is keeping an eye on the MCP Authorization specification evolution and working on having all possible MCP Authorization scenarios supported.
+
+Stay tuned for more updates !