Simplifying MCP: http4k's Updated Authentication Model - Less Code, More Power

May 2025 / the http4k team
http4k MCP logo

We’re excited to share a significant update to our http4k Model Context Protocol (MCP) SDK! 🚀. Based on community feedback and our commitment to making AI integration as frictionless as possible, we’ve streamlined the authentication model in our latest release.

TL;DR - What’s New?

  • Simplified Auth Model: We’ve implemented the new draft specification that requires only resource server capabilities, eliminating the need for dual server implementation
  • Version 6.9.0.0 Released: Available now with these improvements. The docs can be found here
  • http4k-mcp-desktop 1.5.0: Updated desktop client to support the new auth model. Details here
  • Secure Kotlin Client API: Securely connecting to MCP servers is now even easier
  • Same http4k Testability: All our changes maintain the testability-first approach you expect

Why We Made These Changes

The newest (2025-3-26) MCP authentication specification was widely considered too complicated for server creators to implement effectively as it required the MCPs to act as both an OAuth Resource and Authentication servers. The MCP community took this on board and based on feedback from our SDK users, we thoroughly agreed that a simplification was required. From the latest changes in the MCP community around the specification, we’ve embraced the changes in the new draft spec that dramatically reduces this complexity while maintaining robust OAuth security. Whilst these are not yet officially part of the spec, the direction of travel is clear and we believe they are sensible and will be quickly adopted by companies developing production-grade MCP tooling.

At the same time, there have been a number of articles about new attack vectors exposed the MCP space, including DNS-rebinding attacks, malicious browser extensions and Tool Poisoning. We have taken these into account and have made some changes to the way we expose authentication to mitigate these risks (wherever practical for an SDK provider to do so), including making the use of no security at all a deliberate opt-in choice rather than the default. We would encourage the other SDKs authors - and especially the official MCP SDKs - to make similar changes to their APIs to keep the community safe.

For http4k, the developer experience has always been our north star. Along with testability, simplicity, and functional purity, we believe that working with our libraries should feel natural and frictionless. These changes reflect that ongoing commitment to putting developers and organisational data security first.

One-Line Server Setup

Setting up an MCP server with proper authentication is now as simple as using the new simplified auth model with just one parameter addition. This small change means you can create a fully compliant MCP server with OAuth support and minimal ceremony - exactly how http4k should be!

package content.news.`simplifying-mcp`

import org.http4k.core.Uri
import org.http4k.mcp.ToolResponse
import org.http4k.mcp.model.Content
import org.http4k.mcp.model.McpEntity
import org.http4k.mcp.model.Tool
import org.http4k.mcp.protocol.ServerMetaData
import org.http4k.mcp.protocol.Version
import org.http4k.mcp.server.security.OAuthMcpSecurity
import org.http4k.routing.bind
import org.http4k.routing.mcpHttpStreaming
import org.http4k.server.JettyLoom
import org.http4k.server.asServer
import java.time.Instant

fun main() {
    mcpHttpStreaming(
        ServerMetaData(McpEntity.of("foo"), Version.of("bar")),
        OAuthMcpSecurity(Uri.of("https://oauth-server")) { it == "my_oauth_token" },
        Tool("time", "Get the current time") bind {
            ToolResponse.Ok(listOf(Content.Text(Instant.now().toString())))
        }
    ).asServer(JettyLoom(3001)).start()
}

As before, we also have implementations for Basic, Api Key and Bearer token authentication if they are more appropriate for your use case, as well as an option to explicitly opt-in for no security at all (we don’t recommend this but we have left the facility implemented).

Improved Client API

We’ve also made securely connecting to MCP servers more intuitive with our streamlined client connection API which is implemented via a standard http4k Filter. The same simple API for interacting with the server remains the same.

package content.news.`simplifying-mcp`

import content.news.http4k_mcp_has_landed.cityArg
import org.http4k.client.JavaHttpClient
import org.http4k.connect.model.ToolName
import org.http4k.core.Credentials
import org.http4k.core.Uri
import org.http4k.core.then
import org.http4k.filter.ClientFilters
import org.http4k.lens.with
import org.http4k.mcp.ToolRequest
import org.http4k.mcp.client.DiscoveredMcpOAuth
import org.http4k.mcp.client.http.HttpStreamingMcpClient
import org.http4k.mcp.model.McpEntity
import org.http4k.mcp.protocol.Version

val clientCredentials = Credentials("clientId", "clientSecret")
val autoDiscoveryHttp = ClientFilters.DiscoveredMcpOAuth(clientCredentials)
    .then(JavaHttpClient())

// Create an MCP client
val client = HttpStreamingMcpClient(McpEntity.of("My Client"), Version.of("1.0.0"),
    Uri.of("http://localhost:3000/mcp"),
    autoDiscoveryHttp
).apply { start() }

// Call tools programmatically
val toolResponse = client.tools().call(
    ToolName.of("weather"),
    ToolRequest().with(cityArg of "London"),
)

Filters for the other authentication methods are also available, so you can easily switch between them as needed.

Still Fully Testable

True to http4k’s principles, these changes maintain complete testability, allowing you to test authentication flows directly without spinning up real servers.

Staying Ahead of the Curve

Despite what you may have read elsewhere, the http4k MCP SDK remains currently the only production-ready way to run distributed MCPs in a JVM cloud-based or Serverless environment. While official JVM MCP SDKs are still catching up with even the previous spec version, http4k gives you access to the latest features today.

Embrace the change today!

The latest version of http4k supporting these changes is available now through Maven Central. For http4k MCP desktop integration, this update is also available via Homebrew and GitHub releases. Check it out at http4k-mcp-desktop.

What’s Next?

We’re committed to evolving the http4k MCP SDK alongside the official specification. Our focus will always remain on making AI integration simpler, more secure, and more testable - without compromise. We will continue to aim to implement the latest (and sensible!) specification changes as soon as possible so our users can take advantage of them, and maintaining our position as first-to-market with a production-ready MCP SDK for the JVM ecosystem.

As always, the http4k MCP SDK is included in our Pro tier and all Enterprise Edition subscriptions, with free use for non-commercial, non-profit organizations and personal projects.

We’d love to hear how you’re using these improvements! Reach out on GitHub or the Kotlin Slack with your feedback and questions.

Happy coding!

/the http4k team

All News