go -example

This MCP server is an OAuth 2.1 protected MCP server implemented in Go. It shields the MCP endpoints with JWT access token validation using JWKS from the Keycloak authorization server and exposes a simple echo MCP tool for demonstration. You can interact with it through an MCP Inspector or any compliant MCP client by first obtaining an access token, then calling the resource metadata and protected endpoints. The server exposes a resource metadata endpoint that describes the protected resource and the authorization server you must use, and it relies on a JWKS URL to validate tokens locally, ensuring tokens are signed, valid, and scoped appropriately (requires the mcp:tools scope). The included echo tool returns whatever you send, illustrating how requests are processed through the OAuth-protected MCP pipeline.

Prerequisites:

• Go 1.25 or later
• Docker and Docker Compose (for Keycloak setup)

Installation steps:

1. Install Go if you don't have it: download from https://golang.org/dl/ or use your system package manager.
2. Clone or download this repository to your working directory.
3. Install dependencies (Go modules are typically fetched automatically when building):
   • Run: go mod download
4. Start the Keycloak authorization server (provided in the authz-server directory) using Docker Compose:
   • cd authz-server
   • docker-compose up -d This will bring up Keycloak on http://localhost and provide the necessary endpoints for token validation.
5. Run the MCP server:
   • cd ..
   • go run . -authz-server-url="http://localhost/realms/demo" -jwks-url="http://localhost/realms/demo/protocol/openid-connect/certs" -resource-url="http://localhost:8000"
6. Verify the server is running by requesting the protected metadata or attempting an authenticated request via an MCP client.

Notes:

• Ensure Keycloak is configured as described in the README (realm demo, mcp:tools scope, DCR appropriate settings).
• The server expects the JWKS at the specified URL to validate tokens locally.

Tips and notes:

• The server implements RFC 9728 for OAuth 2.0 Protected Resource Metadata and performs JWT validation using JWKS with RS256.
• If you encounter CORS or DCR issues with Keycloak 26.4, the project notes suggest using nginx as a reverse proxy for CORS handling during DCR.
• The MCP Tool provided is a simple echo service used to demonstrate processing through the OAuth-protected MCP pipeline.
• Ensure the -resource-url matches the actual host/port where the MCP server is accessible to clients and the inspector.
• If you modify endpoints or ports, update the -resource-url and JWKS URL accordingly.