Add a blog post about secure MCP SSE server

Author: sberyozkin

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

@@ -0,0 +1,399 @@
+---
+layout: post
+title: 'Getting ready for secure MCP with Quarkus MCP Server'
+date: 2025-04-25
+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 new MCP specification to be widely supported, you can already add authentication to client and server following the https://modelcontextprotocol.io/specification/2024-11-05[previous MCP version].
+
+Indeed, you can use any MCP client that can receive an access token and pass it to the MCP server.
+
+In this post, we will create a https://github.com/quarkiverse/quarkus-mcp-server[Quarkus MCP SSE Server] that requires authentication to access its tools.
+
+We will use Keycloak to login and use a Keycloak JWT access token to access the server with `Quarkus MCP SSE Server Dev UI` in the dev mode.
+
+We will use GitHub to login and use a GitHub binary access token to access the server in the prod mode with both https://modelcontextprotocol.io/docs/tools/inspector[MCP inspector] and the `curl` tools.
+
+[[initial-mcp-server]]
+== Step 1 - Create an MCP server using the SSE transport
+
+First, let's create a secure Quarkus MCP SSE server that requires authentication during the initial Server-sent Events (SSE) handshake and the tool access.
+
+You can find the complete project source in the https://github.com/quarkiverse/quarkus-mcp-server/tree/main/samples/secure-mcp-sse-server[Quarkus MCP SSE Server samples].
+
+[[initial-dependencies]]
+=== 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 MCP SSE transport.
+<2> `quarkus-oidc` is required to secure access to 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 <<initial-configuration>> section below.
+<3> Use the injected `SecurityIdentity` to return the current user's name.
+
+[[initial-configuration]]
+=== Configuration
+
+Finally, let's configure our secure MCP server:
+
+[source,properties]
+----
+quarkus.http.auth.permission.authenticated.paths=/mcp/sse <1>
+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 main and tools endpoints in the configuration, for example: `quarkus.http.auth.permission.authenticated.paths=/mcp/sse,/mcp/messages/*`.
+
+We are ready to test our secure MCP server in the dev mode.
+
+== Step 2 - Access MCP server in the dev mode
+
+=== Start MCP server in the dev mode
+
+[source,shell]
+----
+mvn quarkus:dev
+----
+
+The configuration properties that we set in the <<initial-configuration>> section above are sufficient to start the application in the dev mode.
+
+The OIDC configuration is provided in the dev mode automatically 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 with OIDC immediately. You can also register a custom Keycloak realm to work with 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.
+
+[[oidc_devui]]
+=== Use OIDC Dev UI to login and copy access token
+
+Go to http://localhost:8080/q/dev[Dev UI], find the OpenId Connect card:
+
+image::oidc_devui.png[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"]
+
+[[mcp-server-devui]]
+=== Use Quarkus MCP Server Dev UI to access MCP server
+
+Make sure to login and copy the access token as explained in the <<oidc-devui>> section above.
+
+Go to http://localhost:8080/q/dev[Dev UI], find the MCP Server card:
+
+image::mcp_server_devui.png[MCP Server in DevUI,align="center"]
+
+Select its `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 Keycloak 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 and get a response which contains the `alice` user name:
+
+image::mcp_server_tool_response.png[MCP Server tool response,align="center"]
+
+Now, please stop the server: we are going to prepare it to run in the prod mode next.
+
+== Step 3 - Access MCP server in the prod mode
+
+=== Register GitHub OAuth2 application
+
+Before we start enhancing the MCP server to run in the prod mode, please register a GitHub OAuth2 application.
+
+Follow the GitHub application registration[https://quarkus.io/guides/security-openid-connect-providers#github] process, and make sure to register the `http://localhost:8080/login` callback URL.
+
+Uncomment the lines in `application.properties` which contain `${github-client-id}` and `${github-client-secret}` and replace these two variables with the client id and secret generated by GitHub.
+
+=== Implement Login endpoint
+
+Currently, MCP clients can not use the authorization code flow themselves, therefore we implement an OAuth2 login endpoint which will return a GitHub token for the user to use it with MCP clients which can work with bearer tokens.
+
+Add another dependency to support Qute templates:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-rest-qute</artifactId> <2>
+</dependency>
+----
+
+and implement the login endpoint:
+
+[source,java]
+----
+package org.acme;
+
+import io.quarkus.oidc.AccessTokenCredential;
+import io.quarkus.oidc.UserInfo;
+import io.quarkus.qute.Template;
+import io.quarkus.qute.TemplateInstance;
+import io.quarkus.security.Authenticated;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+
+@Path("/login")
+@Authenticated
+public class LoginResource {
+
+    @Inject
+    UserInfo userInfo; <1>
+    
+    @Inject
+    AccessTokenCredential accessToken; <2>
+
+    @Inject
+    Template accessTokenPage;
+
+    @GET
+    @Produces("text/html")
+    public TemplateInstance poem() {
+        return accessTokenPage.data("name", userInfo.getName()).data("accessToken", accessToken.getToken()); <3>
+    }
+}
+----
+<1> GitHub access tokens are binary and Quarkus OIDC indirectly verifies them by using them to request GutHub specific `UserInfo` representation.
+<2> `AccessTokenCredential` is used to capture a binary GitHub access token.
+<3> After the user logs in to GitHub and is redirected to this endpoint, the access token will be returned to the user in the HTML page generated with Qute.
+
+=== Update the configuration to support GitHub
+
+The <<initial-configuration, configuration>> that was used to run the MCP server in the dev mode was suffient because Keycloak Dev Service was supporting the OIDC login.
+
+To work with GitHub in the prod mode, we update the configuration as follows:
+
+[source,properties]
+----
+%prod.quarkus.oidc.provider=github <1>
+%prod.quarkus.oidc.application-type=service <2>
+
+%prod.quarkus.oidc.login.provider=github <3>
+%prod.quarkus.oidc.login.client-id=github-application-client-id
+%prod.quarkus.oidc.login.credentials.secret=github-application-client-secret
+
+quarkus.http.auth.permission.authenticated.paths=/mcp/sse <4>
+quarkus.http.auth.permission.authenticated.policy=authenticated
+----
+<1> Default Quarkus OIDC configuration requires that only GitHub access tokens can be used to access MCP SSE server.
+<2> By default, `quarkus.oidc.provider=github` supports an authorization code flow only. `quarkus.oidc.application-type=service` overrides it and requires the use of bearer tokens. 
+<3> Use GitHub authorization code flow to support the login endpoint with a dedicated Quarkus OIDC `login` https://quarkus.io/guides/security-openid-connect-multitenancy[tenant] configuration.
+<4> 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.
+
+[NOTE]
+====
+Note the use of the `%prod.` prefixes. It ensures the configuration properties prefixed with `%prod.` are only effective in the prod mode and not interfering with the dev mode. 
+====
+
+=== Install and run application
+
+First, add `quarkus.package.jar.type=uber-jar` to the application.properties.
+
+Now, the application can be packaged and installed using:
+
+[source,shell]
+----
+mvn install
+----
+
+Run it with `jbang`:
+
+[source,shell]
+----
+jbang org.acme:secure-mcp-sse-server:1.0.0-SNAPSHOT:runner
+----
+
+### Login to GitHub and copy the access token
+
+Access `http://localhost:8080/login`, login to GitHub, and copy the returned access token:
+
+image::github_access_token.png[GitHub access token,align="center"]
+
+[[mcp-inspector]]
+=== Use MCP Inspector to access MCP server
+
+Launch https://modelcontextprotocol.io/docs/tools/inspector[MCP inspector]:
+
+[source,shell]
+----
+npx @modelcontextprotocol/inspector
+----
+
+Paste the copied GitHub access token to the `Bearer Token` field and 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 to access MCP server
+
+Finally, let's use `curl` and also learn a little bit how both the MCP protocol and MCP SSE transport work. 
+
+First, access the main SSE endpoint without the GitHub access token:
+
+[source,shell]
+----
+curl -v localhost:8080/mcp/sse
+----
+
+You will get HTTP 401 error.
+
+Use the access token to access MCP server:
+
+```shell script
+curl -v -H "Authorization: Bearer gho_..." localhost:8080/mcp/sse
+```
+
+and get an SSE response such as:
+
+[source,shell]
+----
+< content-type: text/event-stream
+< 
+event: endpoint
+data: /messages/ZTZjZDE5MzItZDE1ZC00NzBjLTk0ZmYtYThiYTgwNzI1MGJ
+----
+
+The SSE connection is created.
+
+Now open another window and use the same access token to initialize the curl as MCP client, and access the tool, using the value of the `data` property to build the target URL.
+
+Initialize the client:
+
+[source,shell]
+----
+curl -v -H "Authorization: Bearer gho_..." -H "Content-Type: application/json" --data @initialize.json http://localhost:8080/mcp/messages/ZTZjZDE5MzItZDE1ZC00NzBjLTk0ZmYtYThiYTgwNzI1MGJ
+----
+
+where the `initialize.json` file has a content like this:
+
+[source,json]
+----
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {
+      "roots": {
+        "listChanged": true
+      },
+      "sampling": {}
+    },
+    "clientInfo": {
+      "name": "CurlClient",
+      "version": "1.0.0"
+    }
+  }
+}
+----
+
+and send the initialization notification:
+
+[source,shell]
+----
+curl -v -H "Authorization: Bearer gho_..." -H "Content-Type: application/json" --data @initialized.json http://localhost:8080/mcp/messages/ZTZjZDE5MzItZDE1ZC00NzBjLTk0ZmYtYThiYTgwNzI1MGJ
+----
+
+where the `initialized.json` file has a content like this:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "notifications/initialized"
+}
+```
+
+And call the tool:
+
+[source,shell]
+----
+curl -v -H "Authorization: Bearer gho_..." -H "Content-Type: application/json" --data @call.json http://localhost:8080/mcp/messages/ZTZjZDE5MzItZDE1ZC00NzBjLTk0ZmYtYThiYTgwNzI1MGJ
+----
+
+where the `call.json` file has a content like this:
+
+[source,json]
+----
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "user-name-provider",
+    "arguments": {
+    }
+  }
+}
+----
+
+Now look at the SSE connection window and you will see the name from your GitHub account returned.
+
+== Conclusion
+
+In this blog post, we have explained how you can easily create a secure Quarkus MCP SSE server, obtain an access token and use it to access the MCP server tool in the dev mode with `Quarkus MCP SSE Server Dev UI` and the prod mode with both the https://modelcontextprotocol.io/docs/tools/inspector[MCP inspector] and the curl tools.
+
+The Quarkus team is keeping a close eye on the MCP Authorization specification evolution and working on having all possible MCP Authorization scenarios supported.
+
+Stay tuned for more updates !