mcp-forge

MCP Forge is a production-ready MCP server template written in Go, designed to integrate with remote providers (such as Claude Web and OpenAI) and local providers. It includes OAuth support and JWT validation options, and is structured to work with both remote and local clients. To run the server in a production-like setup, you can leverage the prebuilt Docker image (achetronic/mcp-forge) which encapsulates the Go binary and its dependencies. The server is designed to be extended inside the internal/tools area for your custom MCP tools and resources, and it ships with examples, a Helm chart, a Dockerfile, and CI workflows to streamline deployment. The README also demonstrates how local clients (like Claude Desktop) can connect via stdio or via a local HTTP proxy setup for remote-style operation.

Prerequisites:

• Docker (recommended for this server image)
• Optional: Go environment for local development or building from source

Installation steps (Docker):

1. Install Docker on your system: https://docs.docker.com/get-docker/
2. Pull and run the MCP Forge image in a container: docker run -i achetronic/mcp-forge
3. (Optional) If you need to customize configuration, mount a config file or environment variables into the container according to your deployment setup. See the project docs for the supported configuration options and YAML/JSON examples.

Local development (optional, if you prefer building from source):

1. Install Go 1.24+ (as recommended by the project): https://golang.org/dl/
2. Clone the repository and navigate to the project root.
3. Build the Go binary and run locally (adjust paths as needed): make build ./bin/mcp-forge --config docs/config-stdio.yaml
4. For stdio development, you can start the server in stdio mode using the provided YAML examples and the Makefile targets (see the README's notes about starting in stdio mode).

Note: The README indicates the server is designed to run in both remote (HTTP) and local (stdio) configurations, with a recommended production path using Helm in Kubernetes and a hashring proxy in front for session routing.

Tips and common considerations:

• The project emphasizes OAuth 8414/9728 compliance and flexible JWT validation (local or via external systems).
• For local development, you can use the stdio transport or enable an HTTP proxy in front of the MCP, which is useful for testing remote client behavior before deploying to production.
• The repository includes a chart/Helm deployment and a Dockerfile to simplify containerized deployment; leverage these for Kubernetes-based environments.
• If you plan to connect local clients (Claude Desktop, Cursor, VSCode) via stdio, you may need to compile the Go binary and point your client to the generated binary and a local config file. For HTTP transport, the mcp-remote package (npm) can be used as a bridge in local development.
• Environment variables related to JWTs and OAuth or candidate claims should be defined according to your deployment’s OAuth provider (e.g., Keycloak) and in accordance with the config examples provided in the docs.
• When using Docker, ensure the image is kept up to date and that you expose any needed ports or mount configuration files as required by your environment.