Troubleshooting
The self-test, logs, and what the common error messages mean.
- Self-test:
/xivmcp selftest(or therun_self_testtool) checks that your plugin provides its Invoke gate, and calls one of your read-only tools if your plugin is enabled. - Logs:
/xllogshows each registration under[XivMcp]. - What the assistant sees: ask the server yourself. The address (port 37521 unless the player changed it) and the token are in
/xivmcp→ Connect. The server answerstools/listwithout aninitializefirst.
curl -s http://localhost:37521/mcp \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'| Symptom | Fix |
|---|---|
Your tool is not in tools/list | The player has not enabled your plugin, or registration failed: check RegistrationFailed. |
| "A tool that isn't readOnly must declare its 'capabilities'" | Add Capabilities = [...]. |
| "A read-only tool can't declare …" | Drop ReadOnly, or the acting capabilities. |
| "'x' is an XIV MCP tool" / "already registered by another plugin" | Use a prefixed name. |
| "… is blocked for … in /xivmcp" | The player denied a declared capability. |
| "The player declined …" | Declined, or not answered within two minutes. |
| "… is suspended by XIV MCP (…)" | A call did something undeclared. Fix the declaration; the player lifts the suspension. |
| "… changed its registration … waits for the player to consent again" | You added a tool or capability. Register everything at startup. |
RequestApprovalAsync is always false | The capability is not declared on that tool. |
| "The background job '…' is running a step" | A job is running and your tool is not read-only. Pause the job first. |
| A cancelled job stays "running" for two minutes | Your handler ignores call.Cancellation. |
| "Unknown tool '…' in a step" / "'…' is not available right now" | A step's tool does not exist, or its plugin is not loaded or not enabled. Declare it with UsesTools; the player sees what is missing on your card. |
| "'…' is not an XIV MCP tool. For another plugin's tool, give 'plugin' …" | A built-in tool name is misspelt, or another plugin's tool lacks its plugin fields. |
| "'…' is built into XIV MCP; declare it with 'tool' alone" | Drop plugin, name, repo and minVersion for XIV MCP's own tools. |
InvalidOperationException or hitches | Game access off the framework thread: use RunOnFrameworkThread. |