Skip to content
SoulFire LogoSoulFire
User guideIntegrations

Connect an AI assistant with MCP

Connect an AI assistant to SoulFire with the Model Context Protocol.

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 manage projects, control bots, run commands, and change settings through natural language.

Install and start SoulFire before you continue. See Get started for installation steps.

Available actions

Through MCP, an AI assistant can:

  • Create and configure projects
  • 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 project configuration

Get an API token

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

  1. The SoulFire GUI: Go to your profile settings and generate an API token
  2. The CLI: Use the generate-token api command
  3. 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.

Connect Claude Desktop

Claude Desktop adds a remote MCP server as a custom connector. The claude_desktop_config.json file is for local servers that Claude starts on your computer.

  1. Open Settings, then Connectors.
  2. Add a custom connector.
  3. Enter the MCP URL, such as https://soulfire.example.com/mcp.
  4. In the request headers step, add Authorization with the value Bearer YOUR_API_TOKEN.

Claude connects to a custom connector through your Claude account, not from your computer. The SoulFire server therefore needs a public HTTPS address. A 127.0.0.1 or LAN address does not work here. See Anthropic's custom connector guide for plan requirements and current menu names. For a local SoulFire server, use Claude Code or another client that connects from your computer.

Connect Claude Code

Claude Code connects from your computer, so a local address works. Replace your-server:port with the SoulFire server address and YOUR_API_TOKEN with the token:

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:

ParameterValue
TransportStreamable HTTP
URLhttp://your-server:port/mcp
Auth HeaderAuthorization: Bearer YOUR_API_TOKEN

Available tools

SoulFire groups its MCP tools by purpose:

Project management

  • list_instances: List all projects visible to the current user
  • create_instance: Create a new project
  • delete_instance: Permanently delete a project
  • get_instance_info: Get detailed project information and configuration
  • update_instance_meta: Update a project name or icon
  • update_instance_config_entry: Update a configuration setting
  • get_audit_log: View the project 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, project, 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 a project
  • 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: Project 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 a project
  • 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 project called "Test Server" and add 5 offline accounts named bot1 through bot5

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

You: Configure the project 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

How is this page?

Last updated on