Docs/Reference/MCP Protocol Support

MCP Protocol Support

Which MCP protocol features XcodeBuildMCP implements, advertises, and does not currently support.

The Model Context Protocol has many optional features. This page documents what XcodeBuildMCP actually implements, so MCP-literate users and MCP clients can evaluate coverage without reading source. Each section links out to the relevant part of the MCP specification.

Tools#

XcodeBuildMCP implements the MCP tools surface:

tools/list returns the active tool set for the current workflow configuration.
tools/call invokes a registered tool and returns MCP content blocks, plus structuredContent when the tool has structured output.

Workflow selection controls which tools appear. By default, only the simulator workflow is enabled. You can enable more workflows through configuration or XCODEBUILDMCP_ENABLED_WORKFLOWS.

When experimentalWorkflowDiscovery is enabled, the manage-workflows tool can add or remove workflows during an MCP session. That changes the active registered tool set.

Tool annotations#

XcodeBuildMCP includes tool annotations in the MCP tools/list response. These are client hints, not security boundaries. See the MCP Tools specification for how compliant clients are expected to use them.

Annotation key	User outcome in a compliant client
`title`	Clients can show a readable name instead of only the machine name.
`readOnlyHint`	Read only tools can be treated as lower risk, and clients may reduce extra confirmations.
`destructiveHint`	Destructive tools can stay behind stronger confirmations.
`idempotentHint`	Tools where calling repeatedly with the same arguments produces the same effect can be safely retried by clients on transient failures.
`openWorldHint`	Clients can treat tools as local operations, not open world operations.

XcodeBuildMCP currently sets title, readOnlyHint, destructiveHint, and openWorldHint on every tool. idempotentHint is supported by the spec but is not currently set on any XcodeBuildMCP tool.

Structured content#

XcodeBuildMCP tools return MCP structuredContent using a consistent envelope.

Every tool call also returns human-readable text content, which is what your agent reads in its conversation ("Build succeeded", a list of simulators, an error message). Structured content is sent alongside that text as a parallel JSON object, so the agent or any automation can consume the result programmatically without parsing prose. Text is for the agent's narrative; structured content is for branching, chaining, and automation.

The envelope wraps every tool's structured payload in the same shape, so consumers can branch on didError and read data against the named schema:

json

{
  "schema": "xcodebuildmcp.output.simulator-list",
  "schemaVersion": "1",
  "didError": false,
  "error": null,
  "data": {}
}

The envelope fields are documented in Output Formats. Canonical JSON schemas live in schemas/structured-output/. Tools advertise their output schema in tools/list.

The one exception is the Xcode IDE bridge: bridge tools forward calls to Xcode's own MCP service, so their output shape comes from Xcode and does not use the XcodeBuildMCP envelope.

Resources#

XcodeBuildMCP exposes the following MCP resources:

URI	Availability	Contents
`xcodebuildmcp://simulators`	Normal MCP sessions	Available iOS simulators with UUIDs and states.
`xcodebuildmcp://devices`	Normal MCP sessions	Connected physical Apple devices with UUIDs, names, and connection status.
`xcodebuildmcp://doctor`	Normal MCP sessions	Development environment diagnostics and configuration status.
`xcodebuildmcp://session-status`	Normal MCP sessions	Runtime session state for log capture and debugging.
`xcodebuildmcp://xcode-ide-state`	Xcode agent sessions only	Current Xcode IDE selection, including scheme and simulator state when available.

The server advertises resource subscriptions and resource list changes during initialize. Current source does not emit runtime resource update or resource list change notifications after startup.

Notifications#

XcodeBuildMCP advertises tools.listChanged support during initialize. See the MCP spec for tools/list_changed.

The Xcode IDE bridge explicitly emits tool list changed notifications when proxied Xcode tools are synced, cleared, or disconnected.

Not implemented today:

MCP progress notifications for long running tool calls.
MCP log-message notifications from the server logger.
Runtime resource update notifications.

Prompts#

XcodeBuildMCP does not currently register MCP prompts. There is no prompts/list or prompts/get support in the server.

Server capabilities (initialize)#

The server advertises this capability shape on initialize: