Skip to content
Back to search

mcp-forge

A complete MCP server template that include vitamins (oauth authentication included)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/achetronic--mcp-forge/badge.svg)](/listings/achetronic--mcp-forge)

HTML

<a href="/listings/achetronic--mcp-forge"><img src="/api/listings/achetronic--mcp-forge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 190 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Forge
  2. ![GitHub go.mod Go version (subdirectory of monorepo)](https://img.shields.io/github/go-mod/go-version/achetronic/mcp-forge)
  3. ![GitHub](https://img.shields.io/github/license/achetronic/mcp-forge)
  4. ![YouTube Channel Subscribers](https://img.shields.io/youtube/channel/subscribers/UCeSb3yfsPNNVr13YsYNvCAw?label=achetronic&link=http%3A%2F%2Fyoutube.com%2Fachetronic)
  5. ![GitHub followers](https://img.shields.io/github/followers/achetronic?label=achetronic&link=http%3A%2F%2Fgithub.com%2Fachetronic)
  6. ![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/achetronic?style=flat&logo=twitter&link=https%3A%2F%2Ftwitter.com%2Fachetronic)
  7. A production-ready MCP (Model Context Protocol) server template (oauth authorization included) built in Go that works with major AI providers.
  8. ## Motivation
  9. The MCP specification is relatively new and lacks comprehensive documentation for building complete servers in Go.
  10. This template provides a fully compliant MCP server that integrates seamlessly with remote providers like Claude Web, and OpenAI,
  11. but with local providers like Claude Desktop too.
  12. ## Features
  13. - 🔐 **OAuth RFC 8414 and RFC 9728 compliant**
  14. - Support for `.well-known/oauth-protected-resource` and `.well-known/oauth-authorization-server` endpoints
  15. - Both endpoints are configurable
  16. - 🛡️ **Several JWT validation methods**
  17. - Delegated to external systems like Istio
  18. - Locally validated based on JWKS URI and CEL expressions for claims
  19. - 📋 Access logs can exclude or redact fields
  20. - 🚀 Production-ready: Included full examples, Dockerfile, Helm Chart and GitHub Actions for CI
  21. - ⚡ Super easy to extend: Production vitamins added to a good juice: [mcp-go](https://github.com/mark3labs/mcp-go)
  22. ## Deployment
  23. ### Production 🚀
  24. Deploy to Kubernetes using the Helm chart located in the `chart/` directory.
  25. ---
  26. Our recommendations for remote servers in production:
  27. - Use a consistent hashring HTTP proxy in front of your MCP server when using MCP Sessions
  28. - Use an HTTP proxy that performs JWT validation in front of the MCP instead of using the included middleware:
  29. - Protect your MCP exactly in the same way our middleware does, but with a super tested and scalable proxy instead
  30. - Improve your development experience as you don't have to do anything, just develop your MCP tools
  31. - Use an OIDP that:
  32. - Cover Oauth Dynamic Client Registration
  33. - Is able to custom your JWT claims.
  34. 👉 [Keycloak](https://github.com/keycloak/keycloak) covers everything you need in the Oauth2 side
  35. 👉 [Istio](https://github.com/istio/istio) covers all you need to validate the JWT in front of your MCP
  36. 👉 [Hashrouter](https://github.com/achetronic/hashrouter) uses a configurable and truly consistent hashring to route the
  37. traffic, so your sessions are safe with it. It has been tested under heavy load in production scenarios
  38. ## How to develop your MCP
  39. ### Prerequisites
  40. - Go 1.24+
  41. ### Modify the code and run
  42. Obviously, you can modify the entire codebase as this is a template, but:
  43. - Most times, you will only need to code inside `internal/tools` directory **to add your MCP Tools and their logic**
  44. - Sometimes, you will need to **add your MCP Resources**. For that, it's recommended:
  45. - To clone `internal/tools` directory into `internal/resources` and rename the structures there
  46. - To add the missing logic in `cmd/main.go` for invoking your code
  47. Run: `make run`
  48. **Note:** Default YAML config executing the previous command start the server as an HTTP server.
  49. To start it as Stdio mode, just modify the Makefile to use other YAML provided in examples.
  50. ### Configuration Examples
  51. #### 🔗 Remote Clients (Claude Web, OpenAI)
  52. Remote clients like Claude Web have different requirements than local ones.
  53. This project is fully ready for dealing with Claude Web with zero effort in your side.
  54. In general, if you follow our recommendations on production, all the remote clients are covered 😊
  55. > [!NOTE]
  56. > Hey! look at the configuration [here](./docs/config-http.yaml)
  57. #### 💻 Local Clients (Claude Desktop, Cursor, VSCode)
  58. Local clients configuration is commonly based in a JSON file with a specific standard structure. For example,
  59. Claude Desktop can be configured by modifying the settings file called `claude_desktop_config.json` with the following sections:
  60. ##### Stdio Mode
  61. If you want to use stdio as transport layer, it's recommended to compile your Go binary and then configure the client
  62. as follows. This is recommended in local development as it is easy to work with.
  63. Execute the following before configuring the client:
  64. ```console
  65. make build
  66. ```
  67. > [!IMPORTANT]
  68. > When using Stdio transport, there is no protection between your client and the server, as they are both running locally
  69. ```json5
  70. // file: claude_desktop_config.json
  71. {
  72. "mcpServers": {
  73. "stdio": {
  74. "command": "/home/example/mcp-forge/bin/mcp-forge-linux-amd64",
  75. "args": [
  76. "--config",
  77. "/home/example/mcp-forge/docs/config-stdio.yaml"
  78. ]
  79. }
  80. }
  81. }
  82. ```
  83. ##### HTTP Mode
  84. It is possible to launch your MCP server using HTTP transport. As most of local clients doesn't support connecting to
  85. remote servers natively, we use a package (`mcp-remote`) to act as an intermediate between the expected stdio,
  86. and the remote server, which is launched locally too.
  87. This is ideal to work on all the features that will be deployed in production, as everything related to how remote clients
  88. will behave later is available, so everything can be truly tested
  89. Execute the following before configuring the client:
  90. ```console
  91. npm i mcp-remote && \
  92. make run
  93. ```
  94. ```json5
  95. // file: claude_desktop_config.json
  96. {
  97. "mcpServers": {
  98. "local-proxy-remote": {
  99. "command": "npx",
  100. "args": [
  101. "mcp-remote",
  102. "http://localhost:8080/mcp",
  103. "--transport",
  104. "http-only",
  105. "--header",
  106. "Authorization: Bearer ${JWT}",
  107. "--header",
  108. "X-Validated-Jwt: ${JWT}"
  109. ],
  110. "env": {
  111. "JWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6..."
  112. }
  113. }
  114. }
  115. }
  116. ```
  117. ## 🌐 Documentation
  118. Do you feel for reading about this topic? I gave you the advice, then don't complain:
  119. 👉 [MCP Authorization Requirements](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#overview)
  120. 👉 [RFC 9728](https://datatracker.ietf.org/doc/rfc9728/)
  121. 👉 [MCP Go Documentation](https://mcp-go.dev/getting-started)
  122. 👉 [mcp-remote package](https://www.npmjs.com/package/mcp-remote)
  123. ## 🤝 Contributing
  124. All contributions are welcome! Whether you're reporting bugs, suggesting features, or submitting code — thank you! Here’s how to get involved:
  125. ▸ [Open an issue](https://github.com/achetronic/mcp-forge/issues/new) to report bugs or request features
  126. ▸ [Submit a pull request](https://github.com/achetronic/mcp-forge/pulls) to contribute improvements
  127. ## 📄 License
  128. MCP Forge is licensed under the [Apache 2.0 License](./LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.