UMCP

uMCP is a lightweight MCP server that connects AI agents to Unity applications using the Streamable HTTP protocol. It emphasizes safety by restricting actions to pre-authorized operations and is designed to be easily extended with custom commands.

How to use

You connect your MCP client to the running Unity project to start interacting with the Unity application. Ensure your MCP client supports Streamable HTTP (for example VSCode Agent Mode, Cursor, or CLINE). The server runs inside Unity and provides an HTTP-based MCP interface accessible at a local URL. Open your MCP client and configure it to point at http://localhost:7225/mcp (or the SSE endpoint at http://localhost:7225/sse) to begin exchanging commands and responses.

How to install

Prerequisites: You need Unity Editor 2022.3 LTS or newer. The MCP client you plan to use must support Streamable HTTP.

1. Install the CoreFramework using Unity Package Manager by adding the package name.

openupm add com.natsuneko.modelcontextprotocol.core-framework

2. Open your Unity project and ensure the CoreFramework loads.

3. Install the Management Tools (and other packages) using Unity Package Manager.

openupm add com.natsuneko.modelcontextprotocol.management-tools
openupm add com.natsuneko.modelcontextprotocol.vrchat-world-tools

If you prefer the Git URL method for adding packages, use these URLs in your Unity Package Manager.

https://github.com/mika-f/uMCP.git?path=/Assets/NatsunekoLaboratory/ModelContextProtocol/CoreFramework

After you add the CoreFramework and start the Unity project, the MCP server automatically starts when Unity runs.

3. (Optional) Install additional management tools via Git URL if needed.

https://github.com/mika-f/uMCP.git?path=/Assets/NatsunekoLaboratory/ModelContextProtocol/MagagementTools

Configure your MCP client

Connect your MCP client that supports Streamable HTTP to the MCP server using the local URL.

http://localhost:7225/sse

http://localhost:7225/mcp

Usage pattern

Open your Unity project, start your MCP client (VSCode Agent Mode, Cursor, CLINE, etc.), and begin interacting. Your client will be able to send pre-authorized commands to the Unity application and receive responses.

Extension

You can extend uMCP by creating your own custom commands and operations using the provided attributes. The following example demonstrates how to create a custom command that can be invoked through the MCP interface.

using System;
using System.ComponentModel;

using NatsunekoLaboratory.ModelContextProtocol.CoreFramework.Attributes;
using NatsunekoLaboratory.ModelContextProtocol.CoreFramework.Models;
using NatsunekoLaboratory.ModelContextProtocol.CoreFramework.Protocol.Abstractions;
using NatsunekoLaboratory.ModelContextProtocol.CoreFramework.Protocol.Interfaces;

namespace NatsunekoLaboratory.Examples.MyCustomCommands
{
    [McpServerToolType]
    public class MyCustomCommand
    {
        [McpServerTool]
        [Description("This is a custom command that does something.")]
        public static IToolResult Execute([Description("An example parameter for the custom command.")] string exampleParameter)
        {
            // Your custom command logic here
            return new TextResult($"Executed custom command with parameter: {exampleParameter}");
        }
    }
}

Notes on safety and extensibility

Safety: The server does not allow the AI to execute arbitrary code. All operations are restricted to pre-authorized commands and operations to prevent unintended actions.

Extensibility: You can add your own commands by implementing a class marked with the MCP extension attributes. This enables you to grow the server’s capabilities without modifying core logic.

Troubleshooting and tips

If the MCP server does not start automatically, verify that Unity is running and that the CoreFramework package loaded correctly. Check for any console errors related to package loading.

Ensure your MCP client is configured to connect to http://localhost:7225/mcp or http://localhost:7225/sse. If you see connection failures, confirm that the Unity application and the client are on the same machine or reachable network-wise.

Available tools

MyCustomCommand.Execute

A sample custom command that can be invoked through the MCP interface by providing an example parameter; demonstrates how to extend the server with new behaviors.