Build Faster With AI Tools

HYTOPIA's SDK was built out of the box to work extremely well with popular AI coding editors and tools like Cursor and Claude Code. Our SDK's development patterns, documentation, and examples make AI assistants capable of building many complex features and ideas using the HYTOPIA SDK with as little as a single prompt.

AI tools are also a fantastic way to assist you in quickly getting up to speed with how to use the HYTOPIA SDK. By using these tools to ask how to implement specific ideas you have, they can fast track you learning how the HYTOPIA SDK works by coding what you're trying to do!

To supercharge your development experience beyond just regular AI tooling, HYTOPIA provides a specialized MCP server that runs in parallel with your development environment.

What is the HYTOPIA MCP Server?

The HYTOPIA MCP (Model Context Protocol) Server provides tools and resources to help developers build games with the HYTOPIA SDK.

It enables AI assistants like Claude to provide accurate, up-to-date guidance specific to HYTOPIA game development. It turns a generalized AI assistant into a supercharged game development expert with full knowledge of the HYTOPIA SDK.

Step 1: Installation

First, let's start by installing the HYTOPIA MCP for a new project, or an existing project. Here's how to do that.

Option 1: New Project Setup

When creating a new HYTOPIA project (Initial Setup), you can have the MCP server automatically configured for you:

bunx hytopia init

During the initialization process, you'll be presented with a questionnaire. Answer the questions, and the MCP server will be set up for you.

The questionnaire will ask you if you use Cursor or Claude Code or both. If you wish to use the cursor MCP server with some other MCP client, the raw STDIO command is at the bottom of this guide.

Option 2: Adding to an existing project

If you're integrating the MCP server into an existing HYTOPIA project:

bunx hytopia init-mcp

Follow the prompts to configure the MCP server for your environment.

Step 2: IDE Configuration

Next up, we need to configure our IDE to use our MCP server so our AI assistant has access to it.

Cursor IDE Setup

1. Make sure you're using the latest version of Cursor

2. Open your project in Cursor IDE

3. Go to Settings > MCP

4. Enable the MCP server

Step 4 showing how to enable the HYTOPIA MCP.

1. The command should automatically be set to bunx with arguments:

["-y", "topia-mcp@latest", "serve", "--dir", "/path/to/your/project"]

Claude Code Setup

When using Claude Code, the MCP server is configured via a .mcp.json file that should have been created during initialization. You can verify it exists in your project root directory.

Using the MCP Server

Once configured, the HYTOPIA MCP Server provides the following tools to AI assistants:

• read_me_first: Provides an overview of the HYTOPIA SDK

• full_game_example: Shows a complete example game

• help: Access help documentation for specific topics

• describe_project: Gets a representation of your project structure

• list_models: Lists available models

• list_audio: Lists available audio files

• get_model_animations: Gets animations for specific models

Best Practices

1. Use Claude 3.5 or Claude 3.7 for optimal results

2. When starting a new project, explicitly ask the AI to check the read_me_first and full_game_example tools

3. For specific implementation questions, direct the AI to relevant sections of the help tool

4. If the AI gets stuck or gives inconsistent answers, start a new chat thread

5. If the AI attempts to run bun index.ts or similar commands to start the HYTOPIA server, reject this tool call and continue normally

Troubleshooting

If the MCP server isn't functioning as expected:

1. Verify the MCP server is enabled in your IDE settings

2. Check that you're in the correct project directory with a valid HYTOPIA project

3. Try reinitializing the MCP server with bunx hytopia init-mcp

4. Restart your IDE

Manually Connecting

If you wish to use the MCP server with a client other than Cursor or Claude Code, you can use the following MCP JSON config:

{
  "mcpServers": {
    "topia-helper": {
      "type": "stdio",
      "command": "bunx",
      "args": [
        "-y",
        "topia-mcp@latest",
        "serve",
        "--dir",
        "/path/to/your/hytopia/server" //<-- The directory with package.json in it!
        // Add "--resources" flag if using resource mode
      ],
      "env": {}
    }
  }
}

Please note that you must replace /path/to/your/hytopia/server with the full path to your HYTOPIA project. This is the folder with package.json.