MCP (AI Integration)

What is MCP?

MCP (Model Context Protocol) lets AI assistants use external tools and services. SoulFire exposes its API as MCP tools. An assistant can control bot instances, run commands, and change settings through natural language.

Install and start SoulFire before you continue. See Start Here for installation steps.

Available actions

Through MCP, an AI assistant can:

Create and configure instances
Start, stop, and restart configured bots independently
Control individual bots (movement, rotation, inventory)
Execute Brigadier commands
Manage Minecraft accounts and proxies
View logs and metrics
Manage users and permissions
Work with visual scripts (node-based automation)
Query server and instance configuration

Get an API token

The MCP endpoint requires a JWT API token. Create one in any of these ways:

The SoulFire GUI: Go to your profile settings and generate an API token
The CLI: Use the generate-token api command
The gRPC API: Call ClientService.GenerateAPIToken or UserService.GenerateUserAPIToken

MCP Endpoint

The MCP endpoint is available at:

http://your-server:port/mcp

The endpoint uses the Streamable HTTP transport.

Connecting Claude Desktop

Add the following to your Claude Desktop MCP configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "soulfire": {
      "url": "http://your-server:port/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Replace your-server:port with the SoulFire server address. Replace YOUR_API_TOKEN with the JWT token.

Connecting Claude Code

For Claude Code (CLI), add the MCP server using:

claude mcp add soulfire --transport http http://your-server:port/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Connect other MCP clients

Use these settings with other MCP clients:

Parameter	Value
Transport	Streamable HTTP
URL	`http://your-server:port/mcp`
Auth Header	`Authorization: Bearer YOUR_API_TOKEN`

Available tools

SoulFire groups its MCP tools by purpose:

Instance Management

list_instances: List all instances visible to the current user
create_instance: Create a new instance
delete_instance: Permanently delete an instance
get_instance_info: Get detailed instance information and configuration
update_instance_meta: Update an instance name or icon
update_instance_config_entry: Update a configuration setting
get_audit_log: View the instance audit log

Account & Proxy Management

add_instance_account: Add an offline Minecraft account
remove_instance_account: Remove an account
add_instance_proxy: Add a proxy (HTTP, SOCKS4, SOCKS5)
remove_instance_proxy: Remove a proxy

Command Execution

execute_command: Execute a SoulFire command (global, instance, or bot scope)
tab_complete_command: Get tab-completion suggestions

Bot Control

set_bots_desired_state: Keep selected bots running or stopped
restart_bots: Reconnect selected bots
get_bot_list: List all bots in an instance
get_bot_info: Get detailed bot information
set_bot_movement: Control WASD, jump, sneak, sprint
reset_bot_movement: Stop all movement
set_bot_rotation: Set view direction (yaw/pitch)
set_bot_hotbar_slot: Change the active hotbar slot
click_inventory_slot: Click inventory slots
get_inventory_state: Get current inventory contents
open_bot_inventory: Open bot inventory
close_bot_container: Close an open container

Server Configuration

get_server_info: Get server settings and plugins
update_server_config_entry: Update server settings

User Management

list_users: List all users
create_user: Create a new user
delete_user: Delete a user
get_user_info: Get user details
generate_user_api_token: Generate an API token for a user

Self/Client Tools

get_client_data: Get current user info and permissions
generate_api_token: Generate a new API token

Metrics & Logs

get_instance_metrics: Instance performance metrics
get_server_metrics: Server system metrics (CPU, memory, etc.)
get_previous_logs: Retrieve recent log entries

Metadata

get_instance_metadata / set_instance_metadata_entry / delete_instance_metadata_entry
get_account_metadata / set_account_metadata_entry / delete_account_metadata_entry

Scripts

list_scripts: List all scripts in an instance
get_script: Get script details and node graph
delete_script: Delete a script
deactivate_script: Stop a running script
get_script_status: Get script execution status
get_node_types: Get available script node types
get_registry_data: Get Minecraft registry data

Example Conversation

Once connected, you can talk to SoulFire in plain language:

You: Create a new instance called "Test Server" and add 5 offline accounts named bot1 through bot5

AI: I'll create the instance and add the accounts for you. Creates instance, then adds 5 accounts with names bot1-bot5

You: Configure the instance to connect to play.example.com and start all five bots

AI: I'll update the server address and set those bots to running. Updates config, then sets the five bot IDs to the running desired state

You: How are the bots doing? Show me their health and positions.

AI: Let me check on your bots. Calls get_bot_list, formats the status information

Security

Use HTTPS to protect API tokens during transfer
API tokens have the same permissions as the user who generated them
Rotate tokens regularly using the generate_api_token tool
Create dedicated users with only the permissions that each assistant needs

MCP (AI Integration)

On this page