Connecting Your Systems

3 min read

Would rather be walked through it one step at a time? Use the guided setup.

You write a web service. Mindfront calls it over HTTP. That’s the whole thing.

No SDK. Nothing installed on your servers. Your code, your machines, any language.

A Fiber bridge

About forty lines · you own both ends of it

If your system is already on the integrations list, skip all of this — Settings → Integrations, sign in, done.

Two endpoints

Endpoint	What it does
`GET /meta`	Returns JSON listing what your service can do
`POST /action/<name>`	Does one of those things, returns JSON

Always return HTTP 200. Errors go in the body, not the status code.

Start with two or three read-only actions. Add ones that write later.

Copy this and run it

#!/usr/bin/env python3
import json
from http.server import HTTPServer, BaseHTTPRequestHandler

META = {
    "protocolVersion": 4,
    "moduleVersion": "1.0.0",
    "moduleName": "OrdersBridge",
    "description": "Answers questions about orders.",
    "actions": [{
        "name": "getOrderStatus",
        "description": "Gets the status of an order by its number.",
        "route": "/action/getOrderStatus",
        "riskLevel": "safe",
        "input": {
            "type": "object",
            "properties": {"orderNumber": {"type": "string"}},
            "required": ["orderNumber"]
        }
    }]
}

def get_order_status(n):          # <- replace with your query
    return {"orderNumber": n, "status": "In production"}

class Bridge(BaseHTTPRequestHandler):
    def reply(self, payload):
        self.send_response(200)
        self.send_header("Content-type", "application/json")
        self.end_headers()
        self.wfile.write(json.dumps(payload).encode())

    def do_GET(self):
        self.reply(META) if self.path == "/meta" else self.send_error(404)

    def do_POST(self):
        body = json.loads(self.rfile.read(int(self.headers.get("Content-Length", 0))) or b"{}")
        if self.path == "/action/getOrderStatus":
            try:
                self.reply({"status": "success", "data": get_order_status(body.get("orderNumber"))})
            except Exception as e:
                self.reply({"status": "failure", "error": {"message": str(e)}})
        else:
            self.send_error(404)

HTTPServer(("", 8080), Bridge).serve_forever()

Open http://localhost:8080/meta. You should see your action listed.

Point Mindfront at it

Settings → Modules → Add Fiber Module

Base URL — where your service is running, as seen from the Mindfront server. localhost on your laptop is not localhost on the server.
Custom headers — leave empty unless your service expects an API key.

It shows Live within about 10 seconds. Mindfront re-reads /meta every 5 seconds, so deploys pick themselves up — nothing to re-register.

Gotchas

Symptom	Fix
An action doesn’t appear	Actions missing `name`, `route`, or a valid `riskLevel` are dropped silently. `riskLevel` must be exactly `safe`, `machineApprovalRequired`, `humanApprovalRequired` or `forbidden`
Module shows Degraded	Open the base URL in a browser on the Mindfront server. If it doesn’t load there it’s a network route, not your code. Also check `/meta` responds in under 5 seconds — don’t query the database in it
Live, but actions never get used	Your `description` fields are too vague. Write them like you’d explain the action to a new colleague
Action times out	100 second limit. For long jobs: one action starts it, another fetches the result

Don’t want to write it yourself

The spec is published as one text file for this. Paste into ChatGPT or Claude with your schema:

Read this first: https://mindfront.engineering/docs/llms-full.txt

Write me a complete, runnable MindFront Fiber bridge in one file.
protocolVersion 4. Three actions, all riskLevel "safe". Every action
needs name, description, route, riskLevel, input. Always return HTTP
200, with errors in the body. Then give me the command to run it.

IT MUST ANSWER:
1.
2.
3.

MY SCHEMA (table names alone are fine):

Full specification · Longer walkthrough