Module Service Protocol - Quick Start

For MSP Version 2

SynthGrid connects to your company’s most valuable tools and data.

Module Service Protocol (MSP) is how—and it’s incredibly easy to get started.

You create a simple web service, and its functions become new abilities that your Synths can use.

MSP is powerful because it’s simple. There are no required SDKs. You use the tools you already know. Your code stays fully private and fully yours.

This is a quick-start guide to get something in 5 minutes. Definitely provide it to SynthGrid, ChatGPT or whatever AI system you are using!

How it works

sequenceDiagram
    participant SG as SynthGrid
    participant YS as Your Service

    SG->>YS: GET /meta
    YS-->>SG: Here's what I can do
    SG->>YS: POST /your/endpoint
    YS-->>SG: Here's the result

What You Need To Build

  1. A Meta endpoint (GET /meta) that describes what your service can do.
  2. Action endpoints (optional) that perform tasks and return JSON.
  3. Data endpoints (optional) that return data for analysis.

1. Meta Endpoint

A GET endpoint at /meta tells SynthGrid what your module can do.

Example Response:

{
  "protocolVersion": 2,
  "moduleVersion": "1.0.0",
  "moduleName": "MyService",
  "description": "A brief description of this service.",
  "actions": [
    {
      "name": "doSomething",
      "description": "Does something useful.",
      "route": "/action/doSomething",
      "riskLevel": "humanApprovalRequired",
      "input": {
        "type": "object",
        "properties": {
          "param1": {"type": "string"}
        }
      }
    }
  ],
  "data": []
}
  • input defines the parameters you want SynthGrid to provide for you.

2. Action Endpoints

These are POST endpoints that do something useful, like perform a task or get some data. They receive JSON and must return JSON.

Success Response:

{
  "status": "success",
  "data": { "result": "The action was successful." }
}

Error Response:

{
  "status": "failure",
  "error": { "message": "Something went wrong." }
}

3. Data Endpoints (Optional)

These are POST endpoints that return raw CSV data.

  • On Success: The response body is just text/csv data.
  • On Failure: The response is a standard JSON error object, just like an action.

Complete Working Example

This minimal Python server correctly implements the protocol.

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

# Define what your module does
METADATA = {
    "protocolVersion": 2,
    "moduleVersion": "1.0.0",
    "moduleName": "HelloWorld",
    "description": "A simple example module that says hello.",
    "actions": [
        {
            "name": "sayHello",
            "description": "Says hello to someone.",
            "route": "/action/sayHello",
            "riskLevel": "safe",
            "input": {
                "type": "object",
                "properties": {"name": {"type": "string"}},
                "required": ["name"]
            }
        }
    ],
    "data": []
}

# The handler for your server
class SimpleMSPHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        # Handle the /meta endpoint
        if self.path == "/meta":
            self.send_response(200)
            self.send_header("Content-type", "application/json")
            self.end_headers()
            self.wfile.write(json.dumps(METADATA).encode())
        else:
            self.send_error(404)

    def do_POST(self):
        # Handle the /action/sayHello endpoint
        if self.path == "/action/sayHello":
            try:
                # Read and parse the JSON input
                content_length = int(self.headers['Content-Length'])
                post_data = self.rfile.read(content_length)
                input_data = json.loads(post_data)

                # Prepare the success response
                name = input_data.get('name', 'World')
                response_data = {
                    "status": "success",
                    "data": {"message": f"Hello, {name}!"}
                }
                
                # Send the success response
                self.send_response(200)
                self.send_header("Content-type", "application/json")
                self.end_headers()
                self.wfile.write(json.dumps(response_data).encode())

            except Exception as e:
                # On failure, return a JSON error body.
                # A 200 status code is fine here because the transport (HTTP) succeeded. SynthGrid will check the body.
                self.send_response(200)
                self.send_header("Content-type", "application/json")
                self.end_headers()
                error_data = {"status": "failure", "error": {"message": str(e)}}
                self.wfile.write(json.dumps(error_data).encode())
        else:
            self.send_error(404)

# Run the server
if __name__ == "__main__":
    print("Starting simple MSP server on http://localhost:8080")
    HTTPServer(("", 8080), SimpleMSPHandler).serve_forever()

Test It

  1. Run the Python script: python3 your_script_name.py

  2. In another terminal, test the endpoints:

    # Get the metadata
curl "http://localhost:8080/meta"

# Call the action
curl -X POST "http://localhost:8080/action/sayHello" \
     -H "Content-Type: application/json" \
     -d '{"name": "Sarah Connor"}'

Connecting to SynthGrid

To connect your running MSP service, ask your SynthGrid administrator for assistance.

That’s It.

Need more details? See the full specification.