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 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.
+
+Indeed, you can use any MCP client that can receive an access token and pass it to the MCP server to start experimenting with MCP authorization, since it https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#2-6-access-token-usage[requires the use of bearer access tokens].
+
+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 !