feat: OpenHexa MCP server (HEXA-1507) by yolanfery · Pull Request #1638 · BLSQ/openhexa-app

yolanfery · 2026-02-23T18:53:23Z

Deploy a remote MCP server with basic tools secured via OAuth 2.1

Note : some areas are not up to our standard quality but this PR serves as a POC to get early feedback and to understand where we should focus first

Changes

MCP server relaying queries using RPC Json
OAuth 2.1 to allow Claude, ChatGPT to authorize usage

How/what to test

Start NGROK to expose your app to the world
You get an URL like https://tommy-someurl-terese.ngrok-free.dev
Use your url + /mcp to configure it in Claude (https://tommy-someurl-terese.ngrok-free.dev/mcp)
Go through the authorization steps
Chat with Claude

Screenshots / screencast

To go further

Audit action per user and show them in the UI or admin panel
Granular authorization (accept only some workspaces/actions)
Tool to get example of pipelines (like validated templates)

yolanfery · 2026-02-24T07:40:20Z

backend/hexa/mcp/views.py

+    if result is None:
+        return HttpResponse(status=204)
+
+    response = JsonResponse(result, status=200)


In general, to fix information exposure through exceptions, keep detailed error information (messages, stack traces) in server-side logs and return only generic, high-level error messages to clients. This preserves debuggability for developers without revealing internal details to callers.

For this specific code, the risky behavior is in backend/hexa/mcp/protocol.py in the handle_jsonrpc function, inside the if method == "tools/call": block. On exception, we currently build a JSON-RPC result that includes "text": str(e). We should instead:

Keep the logger.exception("Tool call failed: %s", tool_name) call so the full traceback is logged.

Replace the client-facing "text": str(e) with a generic error string that does not include details from the exception, e.g. "Tool call failed" or "An internal error occurred while running the tool.".

Optionally, include the tool name or a generic hint if that is acceptable from a privacy standpoint, but avoid echoing exception contents or stack traces.

No changes are needed in backend/hexa/mcp/views.py; the mcp_endpoint view can continue to return the JSON returned by handle_jsonrpc. Only handle_jsonrpc’s error payload needs to be adjusted.

Concretely:

Edit backend/hexa/mcp/protocol.py around lines 106–115.

In the returned dict under "content", replace str(e) with a hard-coded, non-sensitive message.

Do not modify imports or logging configuration.

yolanfery · 2026-02-24T07:46:58Z

backend/config/settings/base.py

+    "ACCESS_TOKEN_EXPIRE_SECONDS": 3600,
+    "REFRESH_TOKEN_EXPIRE_SECONDS": 86400,


I have not tested expiration, something to consider, understand how tools are handling those expirations

yolanfery · 2026-02-24T07:47:34Z

backend/hexa/mcp/graphql/queries.graphql

@@ -0,0 +1,82 @@
+query ListWorkspaces($query: String, $page: Int, $perPage: Int) {


Lets use our graphql layer to avoid code repetition

yolanfery · 2026-02-24T07:48:05Z

backend/hexa/mcp/middlewares.py

+                    token=token
+                )
+                if access_token.expires >= timezone.now():
+                    request.user = access_token.user


The magic to scope actions to user

yolanfery · 2026-02-24T07:49:32Z

backend/hexa/mcp/protocol.py

+def tool(func):
+    _TOOLS[func.__name__] = func
+    return func


No framework/library, just a small registry of tools

yolanfery · 2026-02-24T07:51:00Z

backend/hexa/mcp/protocol.py

+    return func(**arguments)
+
+
+def handle_jsonrpc(body: bytes, user) -> dict | None:


Obviously some parts of this protocol is yet unclear to me (error numbers,...)

But I think we can live with unclear parts of a protocol as long as we verify security

yolanfery · 2026-02-24T07:52:10Z

backend/hexa/mcp/tools.py

+    request.user = user
+    request.bypass_two_factor = True
+
+    result = graphql_sync(


Magic to query our graphql layer directly

yolanfery · 2026-02-24T07:54:44Z

backend/hexa/mcp/tools.py

+# TODO : those tools should be GraphQL mutations instead of REST endpoints, to be consistent with the rest of the API and to leverage GraphQL permissions, validation and audit (to be added).
+#  For now we keep them as simple tools for internal use, but we should migrate them to GraphQL in the future.


We can also ignore them for a v1. But this part of the impressive capabilities of the POC, writing files

In any case they need to be re-worked, don't want to merge those like this.

yolanfery · 2026-02-24T07:55:51Z

backend/hexa/user_management/middlewares.py

            ):
-                return redirect(f"{reverse(settings.LOGIN_URL)}?next={request.path}")
+                return redirect(
+                    f"{reverse(settings.LOGIN_URL)}?next={quote(request.get_full_path())}"


Ensure the connection URL used by LLM tools is fully passed after the login blocker

yolanfery · 2026-02-24T07:58:34Z

backend/hexa/mcp/views.py

@@ -0,0 +1,201 @@
+import json


Lot of lack of understanding here but this is mostly a protocol with some configs

yolanfery added 20 commits February 23, 2026 18:35

init

cfddba8

config app + oauth

90c248e

do not redirect for mcp

796e580

dependencies

e73fd64

config

d809c46

Tools and authorize

a014d5c

Rooting

7e9d024

Wiring

bd06f37

Redirects

4203abc

URL wiring

588b4f3

URL wiring

1ccadce

Oauth URL

2408c8b

Middleware

498f8f7

View

0a5d29e

Queries

075c0c1

Wiring

56340af

Protocol

21428c1

Tools draft

685cceb

Fix

cebe94d

Fix

5024da4

github-advanced-security bot found potential problems Feb 23, 2026

View reviewed changes

fx

6f70ca9

yolanfery commented Feb 24, 2026

View reviewed changes

yolanfery marked this pull request as ready for review February 24, 2026 07:59

yolanfery requested a review from bramj February 24, 2026 07:59

mrivar self-requested a review February 24, 2026 10:35

@@ -109,7 +109,12 @@
                             "jsonrpc": "2.0",
                             "id": req_id,
                             "result": {
-                                "content": [{"type": "text", "text": str(e)}],
+                                "content": [
+                                    {
+                                        "type": "text",
+                                        "text": "An internal error occurred while running the tool.",
+                                    }
+                                ],
                                 "isError": True,
                             },
                         }

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

feat: OpenHexa MCP server (HEXA-1507)#1638

feat: OpenHexa MCP server (HEXA-1507)#1638
yolanfery wants to merge 21 commits intomainfrom
POC3

yolanfery commented Feb 23, 2026 •

edited

Loading

Uh oh!

Check warning

Copilot Autofix

yolanfery Feb 24, 2026

Uh oh!

yolanfery Feb 24, 2026

Uh oh!

yolanfery Feb 24, 2026

Uh oh!

yolanfery Feb 24, 2026

Uh oh!

yolanfery Feb 24, 2026

Uh oh!

yolanfery Feb 24, 2026

Uh oh!

yolanfery Feb 24, 2026

Uh oh!

yolanfery Feb 24, 2026

Uh oh!

yolanfery Feb 24, 2026

Uh oh!

yolanfery Feb 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		"ACCESS_TOKEN_EXPIRE_SECONDS": 3600,
		"REFRESH_TOKEN_EXPIRE_SECONDS": 86400,

		@@ -0,0 +1,82 @@
		query ListWorkspaces($query: String, $page: Int, $perPage: Int) {

		return func(**arguments)


		def handle_jsonrpc(body: bytes, user) -> dict \| None:

		# TODO : those tools should be GraphQL mutations instead of REST endpoints, to be consistent with the rest of the API and to leverage GraphQL permissions, validation and audit (to be added).
		# For now we keep them as simple tools for internal use, but we should migrate them to GraphQL in the future.

Comments

Conversation

yolanfery commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

How/what to test

Screenshots / screencast

To go further

Uh oh!

Check warning

Copilot Autofix

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

yolanfery commented Feb 23, 2026 •

edited

Loading