Add a blog post about secure MCP SSE server

Author: sberyozkin

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

@@ -0,0 +1,227 @@
+---
+layout: post
+title: 'Getting ready for secure MCP with Quarkus MCP Server'
+date: 2025-04-24
+tags: ai mcp security
+synopsis: 'Explain how MCP clients can access secure Quarkus MCP SSE servers with access tokens'
+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.
+
+While it will take a bit of time for the MCP authorization part of the MCP specification be finalized and widely supported, one thing you can be certain about is that MCP authorization compliant clients will be able to login users with the OAuth2 authorization code flow and use bearer tokens to access MCP servers on their behalf.
+
+In the meantime, you can use any MCP client that can accept a bearer access token and send it to the MCP server to start experimenting with MCP authorization.
+
+In this post, we will create a https://github.com/quarkiverse/quarkus-mcp-server[Quarkus MCP SSE Server] that requires authentication for the main and tools SSE endpoints, and test it with `curl`, https://modelcontextprotocol.io/docs/tools/inspector[MCP inspector], and `Quarkus MCP SSE Server Dev UI`.
+
+Please review the https://modelcontextprotocol.io/specification/2025-03-26[latest MCP specification] for a complete explanation of the MCP architecture, core concepts, transports.
+
+== Create MCP SSE server
+
+First, let's create a secure Quarkus MCP SSE server that requires authentication during the initial SSE handshake and the tool access.
+
+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 during the initial handshake. 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.
+
+== Start MCP SSE server
+
+Start the server in the dev mode:
+
+[source,shell]
+----
+mvn quarkus:dev
+----
+
+== Access MCP SSE server
+
+[[mcp-server-devui]]
+=== Use Quarkus MCP Server Dev UI
+
+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.
+
+[NOTE]
+====
+You can login to other providers such as `Auth0` or https://quarkus.io/guides/security-openid-connect-providers#github[GitHub] from OIDC DevUI as well. The only requirement is to update your 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 from Dev UI].
+
+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"]
+
+Next, go to the MCP Server card, select the `Tools` option and choose to `Call` 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"]
+
+Use the `Call` action to make a tool call and get a response which contains the `alice` user name:
+
+image::mcp_server_tool_response.png[MCP Server tool response,align="center"]
+
+[[mcp-inspector]]
+=== Use MCP Inspector
+
+Launch https://modelcontextprotocol.io/docs/tools/inspector[MCP inspector]:
+
+[source,shell]
+----
+npx @modelcontextprotocol/inspector
+----
+
+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.
+
+Use this access token to have MCP inspector connect to the Quarkus MCP SSE server:
+
+image::mcp_inspector_connect.png[MCP Inspector Connect,align="center"]
+
+Next, make a `user-name-provider` tool call:
+
+image::mcp_inspector_tool_call.png[MCP Inspector Tool Call,align="center"]
+
+=== Use curl
+
+Finally, let's use `curl` and also learn a little bit how the MCP protocol and MCP SSE transport work. 
+
+First, access the main SSE endpoint without the access token:
+
+[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 a tool call request to the `data` endpoint:
+
+[source,shell]
+----
+curl -v -H "Authorization: Bearer ey..." -H "Content-Type: application/json" --data @call.json http://localhost:8080/mcp/messages/ZTZjZDE5MzItZDE1ZC00NzBjLTk0ZmYtYThiYTgwNzI1MGJ
+----
+
+where the `call.json` file 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 which contains the `alice` user name:
+
+[source,shell]
+----
+event: message
+data: {"jsonrpc":"2.0","id":2,"result":{"isError":false,"content":[{"text":"alice","type":"text"}]}}
+----
+
+== Conclusion
+
+In this blog post, we have explained how you can easily create a secure Quarkus MCP SSE server, obtain a bearer access token and test it in 
+
+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 !