youtrack

Nothing about a YouTrack project is guessable. Field names, their types, their allowed values, which of them are required, which transitions a state accepts, which link types exist, what a tag does when the issue resolves — every one of these is set per project or per instance, and every one changes what a write must contain. The API reference documents the shapes; only the instance knows the values. Read the project's configuration before the first write, and read it again after changing a field that governs another.

Success is not evidence that anything changed. A command request that asks for no field projection answers 200 with an empty body by design, so the response carries nothing to check. A create can partially fail, applying the issue and silently dropping custom-field writes. A state write on a governed field can be refused by a rule. Read the issue back after every write, and ask for a projection wherever the endpoint offers one.

An empty result never proves absence. YouTrack filters projects and issues hidden from AI tools out of MCP responses without signalling the omission, a collection read truncates at an instance cap when no explicit limit is set, and a query naming no sort returns the most recently updated issues rather than the most relevant. A duplicate search reports what was found, never what exists.

Reach past the tool list

• The tool list is narrower than YouTrack. The MCP server built into YouTrack, at https://<instance>/mcp since 2025.3, has its list reshaped by the connection URL. An operation missing from tools/list may be filtered out rather than absent, and attachments, arbitrary commands, deletion, and link removal have no tool at all. They remain ordinary REST calls.
• Let the server describe its own tools. Names, arguments, and output shapes come from tools/list and from each tool's description, never from memory. The published documentation names the tools but does not carry their full input schemas, and a live schema has been reported rejecting a value the prose documents as valid — so the schema the server returns is the authority, not the help page.
• The issue search tool returns no custom fields. Type, State, Priority, and Assignee need a per-issue read, so filtering on a field the search result omits is a two-pass operation.
• The value shape belongs to the transport, not to YouTrack. REST takes an object where a third-party MCP server may take a plain string. Read the tool's own input schema rather than carrying a shape across transports.
• Confirm the first write on an unfamiliar instance. The tool descriptions call the create and update tools writes; the security section of the same documentation set calls the predefined tools read-only. The contradiction is unresolved in the published material, so treat a first write as unproven until a read returns the new value.
• A project can watch for MCP-originated changes. An on-change workflow rule guarded by ctx.isMcpRequest runs only for requests arriving through the server, so an edit that comes back tagged or audited is configuration, not a defect.