# How to Use Unity MCP CLI Commands via the HTTP API

> Automate Unity MCP using HTTP API commands. Learn how to interact with the Unity MCP server language-agnostically via the /mcp endpoint for seamless integration.

- Repository: [Coplay/unity-mcp](https://github.com/CoplayDev/unity-mcp)
- Tags: how-to-guide
- Published: 2026-07-06

---

**Unity MCP CLI commands communicate with a running Unity MCP server over HTTP JSON-RPC when the server is started with `--transport http`, enabling language-agnostic automation through the `/mcp` endpoint.**

The CoplayDev/unity-mcp repository provides a Python-based Command-Line Interface (CLI) that can execute Unity Editor operations through an HTTP JSON-RPC bridge. By configuring the transport mode to HTTP instead of the legacy stdio pipe, you can invoke Unity MCP CLI commands from any environment capable of making HTTP requests, including CI/CD pipelines, external scripts, and remote services.

## Starting the Server with HTTP Transport

To enable Unity MCP CLI commands via the HTTP API, you must start the MCP server with HTTP transport mode. In [`Server/src/main.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/main.py), lines 120-150 parse the `--transport` flag and related environment variables, while lines 161-170 launch the HTTP server when the transport is set to `"http"`.

### Configuration via Environment Variables

Set `UNITY_MCP_TRANSPORT=http` to enable HTTP mode. The server reads `UNITY_MCP_HTTP_HOST` and `UNITY_MCP_HTTP_PORT` (defaulting to `127.0.0.1:8080`) to determine the binding address for the JSON-RPC endpoint.

```bash
export UNITY_MCP_TRANSPORT=http
export UNITY_MCP_HTTP_HOST=0.0.0.0
export UNITY_MCP_HTTP_PORT=9090
uv run python -m src.main

```

### CLI Arguments

Alternatively, pass the `--transport` flag directly when launching the server:

```bash

# Start with default host/port (127.0.0.1:8080)

uv run python -m src.main --transport http

# Custom configuration with remote hosting enabled

uv run python -m src.main --transport http \
    --http-host 0.0.0.0 \
    --http-port 9090 \
    --http-remote-hosted

```

The [`Server/src/transport/unity_transport.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/unity_transport.py) file contains `_is_http_transport()` (lines 18-20), which checks `config.transport_mode` to determine if HTTP routes should be registered in the plugin hub.

## CLI Client Connection Architecture

When running in HTTP mode, the CLI client implemented in [`Server/src/cli/main.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/cli/main.py) constructs JSON-RPC payloads and POSTs them to the HTTP endpoint rather than communicating through stdio pipes.

### Connection Utility

The [`Server/src/cli/utils/connection.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/cli/utils/connection.py) module implements the low-level HTTP client used by the CLI. Line 112 provides clear error messaging when the HTTP endpoint is unreachable, handling connection retries and TLS configuration automatically.

When you run a command like `mcp-cli status`, the CLI performs an HTTP GET request to `/status` via the connection utility to verify server availability before executing tool commands.

### Configuration Management

The [`Server/src/cli/utils/config.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/cli/utils/config.py) module resolves connection parameters from both environment variables and CLI flags (`--http-url`, `--http-host`, `--http-port`). It constructs a `ConnectionConfig` object that determines the final endpoint URL (e.g., `http://127.0.0.1:8080/mcp`).

## Executing CLI Commands Over HTTP

Once the server is running with HTTP transport, CLI commands follow a JSON-RPC flow through the endpoint defined in [`Server/src/transport/plugin_hub.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/plugin_hub.py) (line 147), which routes requests to the appropriate C# tools in Unity.

### Single Commands

Standard CLI commands translate to JSON-RPC POST requests. For example, creating a GameObject:

```bash
mcp-cli gameobject create --name Cube

```

This serializes to the following JSON-RPC payload:

```json
{
  "method": "gameobject.create",
  "params": {"name": "Cube"},
  "id": 1
}

```

The [`connection.py`](https://github.com/CoplayDev/unity-mcp/blob/main/connection.py) utility POSTs this to `http://127.0.0.1:8080/mcp`, where [`plugin_hub.py`](https://github.com/CoplayDev/unity-mcp/blob/main/plugin_hub.py) resolves the method to [`MCPForUnity/Editor/Tools/ManageGameObject.cs`](https://github.com/CoplayDev/unity-mcp/blob/main/MCPForUnity/Editor/Tools/ManageGameObject.cs) and executes it within the Unity Editor.

Other common operations include:

```bash

# List all open scenes

mcp-cli scene list

# Add a Rigidbody component to a specific object

mcp-cli component add --object-id 12345 --type Rigidbody

# Read the Unity console logs

mcp-cli console read

```

### Batch Execution

For performance-critical workflows, the HTTP API supports batching multiple RPC calls in a single request via [`Server/src/services/tools/batch_execute.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/batch_execute.py):

```bash
mcp-cli batch_execute \
  --commands '[
    {"method":"gameobject.create","params":{"name":"Cube1"}},
    {"method":"gameobject.create","params":{"name":"Cube2"}},
    {"method":"component.add","params":{"object_id":1,"type":"Rigidbody"}}
  ]'

```

The server processes these commands sequentially and returns an array of results, reducing round-trip latency compared to individual HTTP requests for each operation.

## Programmatic HTTP Integration

You can interact with the Unity MCP HTTP API directly from scripts without using the Python CLI wrapper, enabling integration with any language or tool that supports HTTP:

```python
import httpx
import json

payload = [
    {"jsonrpc":"2.0","method":"gameobject.create","params":{"name":"Cube"}, "id":1},
    {"jsonrpc":"2.0","method":"component.add","params":{"object_id":1,"type":"Rigidbody"}, "id":2}
]

resp = httpx.post("http://127.0.0.1:8080/mcp", json=payload)
print(json.dumps(resp.json(), indent=2))

```

This approach allows you to execute Unity MCP CLI commands via the HTTP API from Bash scripts, Node.js applications, or cloud automation platforms.

## Summary

- **Start the server** with `--transport http` or `UNITY_MCP_TRANSPORT=http` to enable the HTTP JSON-RPC endpoint at `http://127.0.0.1:8080/mcp` (configurable via `UNITY_MCP_HTTP_HOST` and `UNITY_MCP_HTTP_PORT`).
- **CLI commands** automatically use HTTP transport when configured, posting JSON-RPC payloads to the `/mcp` endpoint defined in [`Server/src/transport/plugin_hub.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/transport/plugin_hub.py).
- **Batch execution** reduces latency by sending multiple commands in a single HTTP request via the `batch_execute` tool in [`Server/src/services/tools/batch_execute.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/batch_execute.py).
- **Direct HTTP access** allows language-agnostic automation without requiring the Python CLI dependency, using standard JSON-RPC POST requests.

## Frequently Asked Questions

### What port does the Unity MCP HTTP API use by default?

The default port is **8080**, bound to `127.0.0.1`. You can override this using the `--http-port` flag or by setting the `UNITY_MCP_HTTP_PORT` environment variable before starting the server in [`Server/src/main.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/main.py).

### Can I use the Unity MCP CLI without HTTP transport?

Yes, the CLI supports a legacy stdio pipe transport mode. However, HTTP transport is recommended for most use cases as it enables remote access, better error handling in [`Server/src/cli/utils/connection.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/cli/utils/connection.py), and integration with non-Python environments.

### How does the CLI handle connection errors to the HTTP endpoint?

The [`Server/src/cli/utils/connection.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/cli/utils/connection.py) module implements retry logic and provides clear error messages at line 112 if the HTTP endpoint is unreachable. Ensure the server is running with the correct transport mode and that the host/port configuration matches between the server and CLI config.

### Is batch execution more efficient than individual CLI commands?

Yes. The `batch_execute` tool in [`Server/src/services/tools/batch_execute.py`](https://github.com/CoplayDev/unity-mcp/blob/main/Server/src/services/tools/batch_execute.py) processes multiple JSON-RPC requests in a single HTTP POST to `http://<host>:<port>/mcp`, reducing network overhead and round-trip latency compared to executing separate CLI commands sequentially.