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:
- The SoulFire GUI: Go to your profile settings and generate an API token
- The CLI: Use the
generate-token apicommand - The gRPC API: Call
ClientService.GenerateAPITokenorUserService.GenerateUserAPIToken
MCP endpoint
The MCP endpoint is available at:
http://your-server:port/mcpThe 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.
- Open Settings, then Connectors.
- Add a custom connector.
- Enter the MCP URL, such as
https://soulfire.example.com/mcp. - In the request headers step, add
Authorizationwith the valueBearer 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:
| 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:
Project management
list_instances: List all projects visible to the current usercreate_instance: Create a new projectdelete_instance: Permanently delete a projectget_instance_info: Get detailed project information and configurationupdate_instance_meta: Update a project name or iconupdate_instance_config_entry: Update a configuration settingget_audit_log: View the project audit log
Account & Proxy Management
add_instance_account: Add an offline Minecraft accountremove_instance_account: Remove an accountadd_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 stoppedrestart_bots: Reconnect selected botsget_bot_list: List all bots in a projectget_bot_info: Get detailed bot informationset_bot_movement: Control WASD, jump, sneak, sprintreset_bot_movement: Stop all movementset_bot_rotation: Set view direction (yaw/pitch)set_bot_hotbar_slot: Change the active hotbar slotclick_inventory_slot: Click inventory slotsget_inventory_state: Get current inventory contentsopen_bot_inventory: Open bot inventoryclose_bot_container: Close an open container
Server Configuration
get_server_info: Get server settings and pluginsupdate_server_config_entry: Update server settings
User Management
list_users: List all userscreate_user: Create a new userdelete_user: Delete a userget_user_info: Get user detailsgenerate_user_api_token: Generate an API token for a user
Self/Client Tools
get_client_data: Get current user info and permissionsgenerate_api_token: Generate a new API token
Metrics & Logs
get_instance_metrics: Project performance metricsget_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_entryget_account_metadata/set_account_metadata_entry/delete_account_metadata_entry
Scripts
list_scripts: List all scripts in a projectget_script: Get script details and node graphdelete_script: Delete a scriptdeactivate_script: Stop a running scriptget_script_status: Get script execution statusget_node_types: Get available script node typesget_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_tokentool - Create dedicated users with only the permissions that each assistant needs
Related pages
- Manage access and HTTPS for tokens and project permissions
- Configure AI features for AI features inside SoulFire
- HTTP API reference for the endpoints behind the tools
How is this page?
Last updated on
