Example: Create an authenticated mcp-lite server with Hono + Clerk

[brettimus]

What Works

I was able to authenticate with MCP Inspector!

Resources

What I'm reading / using:

• https://clerk.com/docs/nextjs/mcp/build-mcp-server
• https://github.com/clerk/mcp-tools/tree/main
• https://clerk.com/docs/machine-auth/overview

The current code is based on:

• Hono Clerk middleware, which calls authenticateRequest, and uses the result to get the auth object

  • Note that the acceptsToken parameter should be TokenType.OAuthToken, which differs from the Hono Clerk middleware

• Clerk's MCP Server utilities (@clerk/mcp-tools/server) for setting up proper .well-known routes in the API

  • I also used similar utilities for constructing PRM urls and resource urls

Misc Notes

Configuration is necessary:

• Clerk secret key and publishable key, obvs
• Clerk OAuth App with DCR: https://dashboard.clerk.com/last-active?path=user-authentication/oauth-applications
  • However, we didn't need the client id and client secret for this to work

The Clerk authInfo in their Express example is typecast like this:

    // For Clerk authentication
    const clerkAuthInfo =
      authInfo as unknown as MachineAuthObject<"oauth_token">;

The function fetchClerkAuthorizationServerMetadata required that nodejs compatibility flag was enabled in the wrangler.jsonc

The @clerk/mcp-tools package brings in @modelcontextprotocol/sdk types.

Misc TODOs

• Show (in example) use of authInfo

• Investigate intermittent 400 on POST /mcp after authenticating... does not seem to affect functionality in inspector but. Ya know.

• Can we remove and implement our own version of verifyClerkToken? Seems tied specifically to the mcp sdk + its AuthInfo type anyhow, and the logic is dead simple

• Use typegen for the bindings types (AppType)

• File issue with mcp-tools as their README is out of date: Remove refs to nonexistent auth server metadata helpers from README clerk/mcp-tools#7

• Can we remove error="${err.errorCode}", error_description="${err.message}", from the www-authenticate header

• Check if the oauth client id and oauth client secret are necessary to configure in the Hono api?

• Clean up or document the manual construction of the resource url in ".well-known/oauth-protected-resource" handler

• Check if the Clerk middleware for Hono has been updated to support the machine auth beta (UPDATE: It has not)

• File issue with Clerk Docs as the code samples are missing for "js backend sdk" when setting up MCP auth (see here - then select JS Backend from the sdk dropdown on the left)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 074d82c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/fiberplane/mcp/mcp-lite@58

commit: 074d82c