Client reference

Everything is in XivMcpClient.cs, in the namespace XivMcp.Client.

How the client's types fit together.

`XivMcpClient`

Member	Does
`XivMcpClient(IDalamudPluginInterface pluginInterface)`	Connects. Tools are registered again whenever XIV MCP loads.
`void AddTool(McpToolDefinition definition, Func<JsonObject, object?> handler)`	A tool that answers right away, called on the framework thread.
`void AddLongRunningTool(McpToolDefinition definition, Func<McpCall, Task<object?>> handler)`	A tool that may take long; see `McpCall`.
`void RemoveTool(string name)`	Unregisters one tool.
`McpStatus GetStatus()`	Where your plugin stands, the setting of each capability and tool, and each declared dependency.
`McpPermission CheckPermission(string capability)`	`Allow`, `Ask` or `Deny` for one capability (`Deny` unless enabled).
`void UsesTools(params McpDependency[] dependencies)`	Declares the tools your jobs use that are not yours. See Using other tools in your jobs.
`JsonObject StartJob(string name, params McpJobStep[] steps)`	Starts a job; returns it as JSON (`id`, `state`, …).
`JsonObject GetJob(string id)`	One job, by id.
`JsonArray ListJobs()`	The jobs your plugin started.
`void PauseJob(string id)`, `ResumeJob`, `CancelJob`	Job control.
`bool IsAvailable`	XIV MCP is loaded and speaks this API version or a newer one.
`event Action<string>? RegistrationFailed`	XIV MCP's message when a definition is rejected. Log it.
`void Dispose()`	Unregisters everything; call it in your plugin's `Dispose`.

`McpToolDefinition`

public sealed record McpToolDefinition(string Name, string Description)
{
    public string? InputSchema { get; init; }
    public bool ReadOnly { get; init; }
    public bool Destructive { get; init; }
    public string[] Capabilities { get; init; } = [];
}

Property	Meaning
`Name`	3–64 characters `a-z0-9_`, starting with a letter. Prefix it with your plugin's name: `myplugin_…`.
`Description`	What the assistant reads to decide when to call it.
`InputSchema`	JSON schema of the arguments (`"type": "object"`), or null for none. See Arguments.
`ReadOnly`	True if it changes nothing. It needs no capabilities, and may not declare acting ones. While a job step acts, only read-only tools run; others are refused.
`Destructive`	True if the changes are hard to undo. Cannot be combined with `ReadOnly`.
`Capabilities`	`McpCapabilities` ids. Required unless `ReadOnly`.

`McpCall`

What a long-running tool's handler gets.

Member	Meaning
`JsonObject Args`	The arguments of this call.
`CancellationToken Cancellation`	Fires when the job is paused or cancelled, or the app gives up.
`void Progress(string text)`	Adds a line to the job log. Any thread; cut at 300 characters; ignored outside jobs.
`Task<bool> RequestApprovalAsync(string capability, string summary)`	Asks the player now; `true` if approved.
`string Id`, `string Tool`	The call's id and tool name.

Results and errors

Results are serialized with System.Text.Json's web defaults: property names in camelCase, so new { KillCount = 3 } arrives as {"killCount": 3}.
StartJob, GetJob, ListJobs, the job controls and CheckPermission throw McpToolException with XIV MCP's message when it refuses, for example for an unknown tool in a job step. While XIV MCP is not loaded, they throw Dalamud's IpcNotReadyError, so check IsAvailable first. GetStatus returns Unavailable instead. UsesTools and the Add… methods wait for XIV MCP to load, and report refusals through RegistrationFailed instead of throwing. Only an InputSchema that is not valid JSON throws.

`McpStatus`

What GetStatus() returns.

Member	Meaning
`McpPluginState State`	Where your plugin stands. See Showing your status.
`bool CanRun`	True when `State` is `Enabled`.
`string? SuspendReason`	Why XIV MCP suspended your plugin, if it did.
`IReadOnlyDictionary<string, McpPermission> Capabilities`	The player's setting for each capability you declared.
`IReadOnlyDictionary<string, McpPermission> Tools`	What each of your tools is set to as a whole.
`IReadOnlyList<McpDependencyStatus> Dependencies`	Where each tool you declared with `UsesTools` stands.

`McpJobStep`

public sealed record McpJobStep(
    string Tool,
    object? Args = null,
    string? Id = null,
    string? Note = null);

One step of a job: any tool, its arguments (they may use {{stepId.path}} placeholders), an id for later steps to refer to, and a note for the job log.

`McpDependency`

A tool your jobs use, for UsesTools. Create it with one of:

Factory	For
`McpDependency.BuiltIn(string tool)`	One of XIV MCP's own tools, core or integration. XIV MCP knows which plugins it needs or can use.
`McpDependency.FromPlugin(string tool, string plugin, string pluginName, string repo, string minVersion)`	Another plugin's tool: its internal name, its name in the installer, the `https://` URL of its `repo.json` (or `"official"`), and the oldest version that has the tool.

`McpDependencyStatus`

public sealed record McpDependencyStatus(
    string Tool, string State, string Message)
{
    public bool Ok => State == "ok";
}

`State`	Means
`ok`	The tool can be used.
`needs_plugin`	An integration tool needs its plugin, which is not installed or not enabled in Dalamud. Core tools never get this: they work without plugins.
`plugin_missing`	Another plugin's tool, and that plugin is not installed.
`plugin_not_loaded`	Installed, but disabled in Dalamud.
`plugin_outdated`	Installed, but older than your `minVersion`.
`tool_missing`	The plugin is loaded but has not registered the tool.
`not_enabled`	The tool is there, but the player has not enabled its plugin in XIV MCP.

Every state except ok keeps the job step from running. Message says what is wrong, in words the player understands.

ok does not mean the player allows the tool. XIV MCP's own tools still follow the player's module settings, so a step can wait for approval or be refused. The modules and their defaults are listed in Modules and permissions, and each tool's module in the tools reference.

Other types

Type	What it is
`McpToolException(string message)`	An error the assistant sees as it is.
`enum McpPermission { Allow, Ask, Deny }`	A player's setting.
`enum McpPluginState { Unavailable, Undecided, KeptDisabled, Enabled, AwaitingConsent, Suspended }`	Where your plugin stands. See Showing your status.
`static class McpCapabilities`	The capability ids, such as `McpCapabilities.SpendGil`. See Capabilities.

Client reference

XivMcpClientCopy Anchor Link

McpToolDefinitionCopy Anchor Link

McpCallCopy Anchor Link

Results and errorsCopy Anchor Link

McpStatusCopy Anchor Link

McpJobStepCopy Anchor Link

McpDependencyCopy Anchor Link

McpDependencyStatusCopy Anchor Link

Other typesCopy Anchor Link

On this page