Skip to main content

HTTP API

In addition to the stdio transport, OpenForge MCP supports an HTTP transport. HTTP mode lets you call tools via a REST API and connect multiple clients simultaneously.

Starting the Server​

# Start on the default port (8080)
uvx openforge-mcp --transport http

# Specify a port
uvx openforge-mcp --transport http --port 3000

# Specify host and port
uvx openforge-mcp --transport http --host 0.0.0.0 --port 3000

REST API Endpoints​

List Tools​

GET /tools

Retrieves a list of all available tools.

curl http://localhost:8080/tools

Example response:

{
  "tools": [
    {
      "name": "list_tools",
      "description": "Retrieve a list of available tools"
    },
    {
      "name": "get_tool_schema",
      "description": "Retrieve the parameter schema for a specified tool"
    },
    {
      "name": "call_tool",
      "description": "Execute a specified tool"
    }
  ]
}

Get Tool Schema​

GET /tools/:tool_name/schema

Retrieves the parameter schema for a specified tool.

curl http://localhost:8080/tools/create_gameobject/schema

Example response:

{
  "name": "create_gameobject",
  "description": "Create a new GameObject in the Unity scene",
  "parameters": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Object name"
      },
      "type": {
        "type": "string",
        "enum": ["Empty", "Cube", "Sphere", "Cylinder", "Plane", "Capsule"],
        "description": "Primitive type"
      },
      "position": {
        "type": "object",
        "properties": {
          "x": {"type": "number"},
          "y": {"type": "number"},
          "z": {"type": "number"}
        }
      }
    },
    "required": ["name"]
  }
}

Execute a Tool​

POST /tools/:tool_name

Executes a specified tool.

curl -X POST http://localhost:8080/tools/create_gameobject \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyCube",
    "type": "Cube",
    "position": {"x": 0, "y": 1, "z": 0}
  }'

Example response:

{
  "success": true,
  "result": {
    "id": "a1b2c3d4",
    "name": "MyCube",
    "type": "Cube",
    "position": {"x": 0, "y": 1, "z": 0}
  }
}

Take a Screenshot​

POST /tools/take_screenshot
curl -X POST http://localhost:8080/tools/take_screenshot \
  -H "Content-Type: application/json" \
  -d '{
    "width": 1920,
    "height": 1080
  }' \
  -o screenshot.png

Server Status​

GET /health

Check the server's running status and connected applications.

curl http://localhost:8080/health

Example response:

{
  "status": "ok",
  "connections": {
    "unity": true,
    "blender": false,
    "godot": false
  },
  "version": "0.5.0"
}

Multi-Agent Configuration​

In HTTP mode, multiple AI clients can connect to the same OpenForge MCP server. This enables multi-agent setups.

Agent A (scene design) ------\
                              +----> OpenForge MCP Server ----> Unity
Agent B (materials)   ------/          (HTTP)

Configuration Example​

Start a single OpenForge MCP server in HTTP mode and connect multiple clients to it.

# Start the server
uvx openforge-mcp --transport http --port 8080

Each agent sends requests to the same endpoint. Mutual exclusion is handled on the server side, so data conflicts from concurrent requests do not occur.

Integration with Scripts​

The HTTP API lets you call tools directly from shell scripts or Python scripts.

Shell Script Example​

#!/bin/bash
# Script to batch-place objects in a Unity scene

SERVER="http://localhost:8080"

# Place 5 cubes
for i in $(seq 0 4); do
  curl -s -X POST "$SERVER/tools/create_gameobject" \
    -H "Content-Type: application/json" \
    -d "{
      \"name\": \"Cube_$i\",
      \"type\": \"Cube\",
      \"position\": {\"x\": $((i * 2)), \"y\": 0, \"z\": 0}
    }"
  echo ""
done

Python Script Example​

import requests

SERVER = "http://localhost:8080"

def call_tool(tool_name: str, params: dict) -> dict:
    response = requests.post(
        f"{SERVER}/tools/{tool_name}",
        json=params
    )
    return response.json()

# Create a material and apply it to an object
call_tool("create_material", {
    "name": "RedMaterial",
    "color": {"r": 1, "g": 0, "b": 0, "a": 1}
})

call_tool("set_material", {
    "target": "MyCube",
    "material": "RedMaterial"
})

CI/CD Integration​

You can use the HTTP API to automate Unity builds and scene validation from CI/CD pipelines.

GitHub Actions Example​

name: Scene Validation

on: [push]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start OpenForge MCP
        run: |
          uvx openforge-mcp --transport http --port 8080 &
          sleep 3

      - name: Validate scene objects
        run: |
          RESULT=$(curl -s http://localhost:8080/tools/get_scene_info)
          echo "$RESULT" | python -c "
          import sys, json
          data = json.load(sys.stdin)
          objects = data['result']['objects']
          assert len(objects) > 0, 'No objects in scene'
          print(f'Validation complete: {len(objects)} objects')
          "