--- title: "YouTrack MCP Server: Turning the Project System of Record into a First-Class AI Tool at Spotware" description: "A custom-built MCP (Model Context Protocol) server that gives every AI assistant in the company deep, multi-account, agent-optimized access to YouTrack — issues, Knowledge Base articles, project schema, and commands, read and write — with navigable reading of documents too large to read in one pass, failures that teach an assistant the fix instead of sending it in circles, batch fetch, change history, attachment access, and ChatGPT Company Knowledge support." date: "2025-02-01T07:00:00Z" last_updated: "2026-08-06" build_time: "2026-08-25T02:13:21Z" project_name: "YouTrack MCP Server" project_description: "A production MCP server built at Spotware that gives AI assistants deep, agent-optimized, multi-account access to YouTrack — issues, Knowledge Base articles, project schema, comments, and commands, read and write. It makes oversized specifications, tickets, and discussion threads navigable instead of unreadable, turns a failed call into a correction that teaches the fix, and adds batch fetch, change history, attachment access, and ChatGPT Deep Research / Company Knowledge compatibility." status: "Active" period_from: "2025-06-02" client: "[Spotware Systems](https://www.spotware.com/)" related_skills: ["artificial-intelligence","product-management","project-management","system-analysis","stakeholder-management","software-development","python","quality-assurance","rest-api","openapi-specification","kubernetes","mcp"] related_projects: ["air-api","aila"] related_experience: ["ai-product-manager-at-spotware"] keywords: ["YouTrack","Model Context Protocol","MCP Server","AI-Assisted Engineering","Knowledge Base","Issue Tracking","AI Product Management"] license: "https://creativecommons.org/licenses/by/4.0/" canonical: "https://www.alexfeel.info/projects/youtrack-mcp-server/" --- ## Overview The **YouTrack MCP Server** is a custom MCP (Model Context Protocol) server built at Spotware that turns YouTrack — the company's primary system of record for product and engineering work — into a **first-class AI tool**. It gives any AI assistant clean, agent-friendly access to the issues, links, projects, custom fields, and Knowledge Base articles that capture how the business actually runs: requirements, decisions, discussions, dependencies, incidents, and delivery history. It reads that system of record and, when the caller supplies a personal access token, writes back to it — creating and updating issues and articles, commenting as the real person, and running YouTrack commands. It has been in production since **June 2025**, months before JetBrains shipped its own remote MCP server with YouTrack 2025.3 in late 2025, and the investment in it has only deepened since: the two capabilities our workflows lean on hardest — reading documents that are too large to read, and failing in ways that teach an assistant the fix — still live only in ours. It also serves every user from their own account without giving up the cross-team reach the company wants. ## The Problem YouTrack is the source of truth for how product and engineering work happens at Spotware: requirements live there, decisions get logged there, dependencies and history are traceable there. Without direct AI access to that system of record: - Analysts, PMs, and developers spend significant time **manually searching and cross-referencing tickets** for context that already exists. - AI agents stay **blind to a primary system of record**, which forces every AI-assisted workflow to either operate with incomplete grounding or push the human back to a YouTrack browser tab to copy-paste the missing context in. - New AI use cases (research, investigation, drafting, summarization) hit the same dead end every time: the AI cannot reach the project history. The YouTrack MCP Server was built to remove that friction at the **system layer**, not per-tool — so any MCP-aware AI assistant in the company gains YouTrack access by configuration, not by integration work. ## The Solution The server exposes a compact, agent-optimized surface to AI clients — spanning both reading and writing: - **A full read surface over issues and the Knowledge Base.** Issue search with the complete YouTrack query language, single and order-preserving _batch_ issue fetch, issue links, issue and article comments, counting how many issues match a query without pulling them back, project discovery, and one-call project-schema discovery (every custom field's type, required flag, and allowed values). For the Knowledge Base: search, full article content, article comments, and tree navigation. Reading a link hands back the literal command phrase that recreates it, so a relationship an assistant has just read is one it can reproduce elsewhere without guessing at YouTrack's internal type names. Saved searches and a current-user identity check round it out, so an agent can build correct queries on its own and know whose eyes it is looking through. - **Change history, not only current state.** What a tracker shows you is the end of a story. An assistant can also ask who moved an issue to which state and when, who reassigned it, what the description said before someone edited it, and how an article's text changed between two dates — narrowed to a single field, a single person, or a window of time, and paged like every other read. This is what turns a logged decision into an answerable question: not just what a ticket says today, but when it started saying it and who made it say so. - **Write and authoring tools, gated behind the caller's own token.** Create and update issues and articles, comment on both as the real person, and set typed custom fields in the same request. The piece no built-in tool replicates is `apply_command`, which runs _any_ YouTrack command — state, assignee, priority, tags, sprints, work items — across one or many issues, pre-flighted through YouTrack's own command-assist, with dry-run previews and an explicit confirmation gate for destructive deletes. - **Attachment access.** Tools resolve pre-authenticated attachment URLs on issues, articles, and comments, so an agent can follow the files a ticket references, not just its text. - **Agent-first ergonomics.** Curated compact responses by default (flattened custom fields, ISO-8601 timestamps, absolute URLs, previews) with a raw-JSON escape hatch for granular field, link-field, and custom-field selection; deterministic pagination envelopes; and the exact YouTrack query and command grammar placed where the model will actually receive it, so assistants get it right on the first attempt. That last one turns out to be a plumbing problem rather than a writing one: a complete grammar reference is far larger than what real AI clients accept in a tool description, and they disagree about what happens next — one family cuts the text off silently, telling neither the model nor anyone watching, while another refuses the entire tool list because a single description ran long. So the reference travels in whichever channel a client keeps: a short description that stands on its own, the full grammar attached to the parameter the model is filling in, and a tool that hands the reference over on request. The sizes are pinned by tests, because a limit nobody enforces is a limit you rediscover in production. Each tool also carries a short discovery hint, with the two search entry points marked to load always, so a client that only loads a ranked subset of the tool surface can still find its way to the rest on the first turn. ## Reading Documents Too Large to Read A tracker that has been running for years accumulates entities nobody can read in one sitting: specifications that run to book length, incident tickets whose comment thread dwarfs the ticket itself, Knowledge Base pages that have been growing for a decade. For an AI assistant these are worse than merely long. Either they blow the context budget outright, or — the more dangerous outcome — they arrive silently cut off, and the assistant reasons with complete confidence on a fragment without ever learning that a fragment is what it got. The server lets an assistant work through a large document the way a person does: take in its structure first, pull only the part that matters, then pick up from exactly where it stopped. The same discipline covers long discussion threads and multi-item fetches, so no single request can run past a predictable answer size. Every partial answer is self-describing — it states what was served, what remains, and precisely which follow-up call retrieves the rest, so continuing never depends on the assistant guessing. Search is closed into the same loop: a hit can carry the matching passages themselves, positioned so the assistant can jump straight to reading that spot instead of re-fetching the whole document to find it. Bounding an answer is easy. Bounding it without lying about it is not. The totals have to describe the whole document even when only a slice ships, the coordinates have to survive every transformation the text went through, the boundaries have to fall where they will not corrupt structured content, and all of it has to stay cheap and predictable while the document is enormous and other people are being served at the same time. There is a related problem underneath. A long-lived tracker holds content written under several generations of its own authoring format, and the documents most likely to carry the original decisions are usually the oldest ones. Reads hand back one consistent, modern text whatever era the content was written in — readable prose rather than raw markup — and the response says plainly when it has done so. Everything derived from that text (structure, positions, excerpts, totals) describes the same canonical version, so a coordinate an assistant is handed in one call still means the same thing in the next. A caller that wants the stored original byte for byte can still have it, and nothing written back is ever altered. Deciding whether a body is markup from the older regime or ordinary prose that merely looks like it is a judgment call with an asymmetric cost of being wrong — and on the largest documents that conversion is expensive enough that doing it naively would degrade service for everyone else on the server. Between them, the documents that carry the most decision history — exactly the ones worth grounding an answer in — are routinely usable, at a small fraction of the context cost of a naive full read. ## Failures That Teach the Fix Much of the engineering in this server goes into what happens when an AI assistant gets something wrong, because in practice that is a large share of what happens. Models compose queries from half-remembered grammar, borrow argument names from the response they just read or from a different vendor's tool that did a similar job, and ask for things in the most expensive way available. Each near-miss costs a full turn, and a generic rejection costs three or four more while the model mutates the wrong thing — sometimes converging on a query that "works" only because it quietly dropped a filter. So the server answers failures with corrections rather than complaints. Where a rejection has several plausible causes at once, it distinguishes them and returns the one that actually applies, so a failure typically closes in a single retry instead of a spiral; where the cause is genuinely ambiguous, it says so and names both recoveries rather than confidently picking one. Where an argument name is a recognizable near-miss, the call completes as intended — without ever letting a repair override something the caller genuinely asked for. Where a malformed query can be provably repaired without changing what it asks, the server repairs it, runs it again as the same person, and says in the answer that it did so; where it will not act unasked, it hands back the caller's _own_ query corrected rather than a generic example, because a model shown an example tends to rewrite its question to match the example. Where a request would work but is the expensive or wrong-shaped way to get the answer, the response names the tool that answers it directly. And where a call cannot be salvaged, the rejection is one compact line in the vocabulary the caller can actually see, naming every problem at once: no internals, no documentation links, no essays. Production traffic showed what a bare rejection does to a model that wants to succeed: it recovers by deleting the part it suspects — a filter, one branch of an _or_ — and then answers a different question from the one it was asked, with every appearance of having answered the original. So a correction states the consequence of the tempting wrong move alongside the fix, and the one query shape that comes back with a full, well-formed result set wider than the filters the caller actually wrote is flagged in the response, even though the platform reports it as a success. > [!IMPORTANT] The failures that never announce themselves > > Some malformed requests are not rejected by the platform at all. They are accepted, they return success, and they hand back plausible, well-formed, **wrong** results — the assistant never learns that anything went wrong, and neither does the human reading the answer. The server recognizes those shapes and refuses them before they are ever issued, explaining the correct form instead. Choosing a clean refusal over a confidently wrong answer is one of the highest-leverage reliability decisions in the whole system, and it is invisible in any feature list. Not every failure is the assistant's, and the other kind needs the opposite advice. When the platform itself is down, the request was right, so the server tells a reader to try once more and then to wait and say so plainly, rather than rewording a request that was never the problem — which is exactly the reflex an outage otherwise triggers, at the moment it is least useful. A writer gets the distinction that actually matters mid-outage: whether the write certainly never left, or might already have landed on the far side of a connection that broke before the answer came back. In the second case the instruction is to check before repeating, because a duplicated comment, status change, or command is a worse outcome than a failed one. And a timeout buried inside a larger answer surfaces as the failure it is instead of being served as an absence. None of this comes from reading the vendor's documentation. It comes from mining production behavior: identifying how real assistants actually fail against this platform, then verifying empirically what the platform truly does in each case, one controlled experiment at a time against a live system — and repeatedly finding the documentation wrong or incomplete. The hard part was never writing better error strings. It is deciding which of several true statements is the _useful_ one for a model to receive, and keeping it compact and machine-actionable. That loop only exists because the system is built to be watched. Production output is deliberately shaped so agent behavior is **measurable**: every expected failure leaves exactly one line, in one place, in a form that severity-based alerting and log analytics can parse, with the underlying stack's per-request noise suppressed so real problems are not buried in it. Questions like "how often do assistants come back empty, and on what shape of request?" get answered from production data instead of guessed at — and those answers are what surface the next failure class worth closing. ## Working as Yourself — or Without a Token A single shared service account is enough to _read_ a system of record, but it can never represent the many different people using it: a comment or a status change made through a shared bot loses the one thing that makes it meaningful — _who_ did it — and any one account either sees too little for cross-team work or too much to be safe. So the server runs **many accounts through one deployment**. Every request may carry the end user's own YouTrack personal access token, and the behavior follows from who is asking: - **Writes are always the real person.** Creating an issue, editing an article, leaving a comment, or running a command requires a personal token and is attributed to that user — never to a faceless service account. With no token, the write tools decline with a clear explanation instead of acting anonymously. - **Reads try your token first, then reach further.** A read is attempted with your own token; if YouTrack hides an entity from you, the server transparently retries through the shared read-only service account and flags the answer as such — so cross-team investigations still land, and reads can deliberately reach _beyond_ your own permissions where the company wants that shared visibility. - **It works with no token at all.** A client configured without a personal token serves anonymous reads through the service account, so one configuration can be handed to everyone unchanged — and simply _upgrades itself_ the moment a user adds their own token. Personal tokens are never logged and never used as cache keys — only a one-way digest is — and token-scoped responses bypass the caches entirely, so one person's private visibility can never leak into another's results. Queries about _me_ refuse to resolve through the service account, so "issues assigned to me" always means the real caller or an explicit error, never a misleading fallback. Partial visibility is the normal case rather than the exception, and the server keeps answering through it. One inaccessible corner of a larger answer is marked as inaccessible and the rest is served intact, instead of a single bad reference collapsing the whole request. Where YouTrack disguises a permissions gap as plain absence — answering "you may not see this" with something no status code can distinguish from "there is nothing here" — the server recognizes the disguise, recovers the answer where it legitimately can, and says plainly that it did, rather than returning an empty result the caller would reasonably read as "there is nothing there". Where recovery genuinely is not possible, the response names the real condition and the way around it instead of a dead end. ## YouTrack Inside ChatGPT Company Knowledge Corporate ChatGPT can treat an MCP server as a **Company Knowledge** source for Deep Research — but only if that server exposes _exactly_ two actions, `search` and `fetch`, shaped to OpenAI's connector contract. A server with a rich, named tool surface (like the full YouTrack tool set) is turned away from that mode. So the deployment runs **two MCP servers side by side from one process**: the full tool surface for general MCP clients, and a second, dedicated endpoint that exposes only the standards-compliant `search` + `fetch` pair. That second endpoint is what lets YouTrack register as a Company Knowledge source in corporate ChatGPT. Its `fetch` returns not just an issue's or article's body but the discussion under it — complete, never trimmed to fit, and delivered in sequential parts when the material is large — because the decision, the caveat, and the "why" usually live in the conversation, not the description. Company Knowledge answers are then grounded in the whole discussion, not only the headline. ## Where It Goes Beyond the Official Server In late 2025, JetBrains shipped an official remote MCP server built into [YouTrack 2025.3](https://www.jetbrains.com/youtrack/whatsnew/2025-3/), and it has grown quickly: a couple of dozen read-and-write tools across issues, Knowledge Base articles, projects, users and groups, saved searches, and time tracking, on both YouTrack Cloud and self-managed Server, reachable from any standard MCP client with either a token or a browser sign-in. It is a capable first-party option, a great deal of what our server does it does too, and JetBrains has said publicly that it intends to keep expanding the set — so the comparison below is a snapshot of two tool surfaces, not a verdict. Ours stays in production alongside it because of what happens at the edges: when a document is too big to take in at one go, or when the assistant asks for the wrong thing. The comparison is deliberately scoped to each server's **built-in tool surface**: the official server is extensible with custom tools shipped in YouTrack app packages, so a site _could_ script some of this in, but it is not there out of the box. | Capability | Our YouTrack MCP Server | Official YouTrack MCP Server | | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Navigable reading of oversized issues, articles, and comment threads | Yes — structure first, then any addressed region, with self-describing continuation | Line-based scrolling inside a single article is documented, and list responses page by offset and limit; nothing documented for an oversized issue body or one long comment thread | | Corrective failures — ranked diagnosis, grammar teaching, refusal of requests the platform would answer wrongly | Yes | Not a documented feature of the built-in tools | | One consistent modern text for content written under any generation of the authoring format | Yes — all derived positions computed over it, with the stored original available on demand | Not documented | | Batch issue fetch by ID (many full issues in one call) | Yes — order-preserving, with per-item error placeholders | No documented batch-by-ID tool; single-issue fetch, with several issues arriving only from query-based search in a fixed result shape | | Change history on issues and articles — who changed which field, when, and from what to what | Yes — narrowed to one field, one person, or one window of time, and paged like any other read | Not documented for the built-in tools | | Attachment access (URLs and metadata) on issues, articles, and comments | Yes | Not documented for the built-in tools | | ChatGPT Deep Research / Company Knowledge (`search` + `fetch` contract) | Yes — dedicated endpoint; the discussion travels complete with the document | Not eligible — one endpoint with many named tools (usable only as a general ChatGPT connector) | | Raw field / link-field / custom-field selection | Yes — curated by default, raw YouTrack JSON on demand | Fixed documented response shapes; the per-call options choose which _tools_ are offered, not which fields come back | | Reading Knowledge Base article _comments_ | Yes | Issue comments only — no documented article-comment tool | | Arbitrary YouTrack command execution (`apply_command`) | Yes — any command, assist pre-flight, dry-run, delete guard | No documented free-text command tool (only structured issue mutations) | | Credential model | Personal-token-first, with shared service-account read fallback and token-less anonymous read | Always the calling user's own account and permissions, by security design — no anonymous mode, and a site can additionally hide projects and issues from AI tools altogether | These differences are not abstract. Agent workflows that read a decade-old specification without drowning in it, that bulk-fetch dozens of related issues in one shot, that reconstruct when a decision was taken and who took it, that open the files a ticket links, that register YouTrack as a Company Knowledge source in ChatGPT, that trim payloads to exactly the fields a task needs, that read the discussion under a Knowledge Base article, or that drive a state transition with a raw YouTrack command all lean on something the documented built-in tool set does not offer today. Where the two overlap — issue and article read/write, project schema, saved searches, issue comments — the official server covers the ground well, and reaching for it there is the right call. Where they differ, the gap is less about which tools exist than about what happens when the content is large or the assistant is wrong. The official server's strict per-user permission model, in particular, is a deliberate least-privilege design rather than a shortcoming; our broader-reaching read is simply a different, more permissive posture that our cross-team work happens to want. ## Integrations The server is deployed across the AI-assisted toolchain Spotware uses every day: - **AI-assisted development and analysis.** Engineers, analysts, and PMs reach the YouTrack MCP Server from MCP-aware tools such as **Claude Code**, **Windsurf**, **Cursor**, and **VS Code Copilot Chat** — pulling YouTrack context directly into coding, specification, and investigation workflows, and, with their own token, filing and updating work without leaving the IDE. - **Corporate ChatGPT, including as a Company Knowledge source.** The dedicated Deep Research endpoint (see above) exposes the standards-compliant `search` and `fetch` pair required to register as a Company Knowledge source, so teams get YouTrack-grounded answers — the full discussion included — directly in the assistant they already use. - **Cross-AI investigations.** Because the same server speaks to multiple AI clients, an investigation started in one tool (a developer asking Claude Code about a regression's history) can continue in another (a PM asking ChatGPT about the same issue's product context) without losing the YouTrack grounding. ## Measurable Impact The figures below come from production instrumentation rather than a usage-metering product, so they are stated as floors: the observed traffic supports at least this much. It is also a rising line rather than a plateau — the volume has multiplied several times over as more teams and more agent workflows have come online — so each number is the low end of a moving one. - **Tens of thousands of AI tool calls a month**, and several hundred on an ordinary working day. The traffic spreads across most of the tool surface and a long tail of issues — well over a hundred distinct ones inside a single working week — rather than circling a few hot ones. - **The shape of the traffic is what identifies it as people rather than automation.** It follows the working day — busy through business hours, quiet overnight, still ticking over at the weekend — and it comes from analyst, PM, and developer workflows rather than from a scheduled job. - **Meaningful time saved on ticket discovery and investigation** — work that otherwise requires browser-based search and cross-referencing happens inline in the AI assistant. - **Production-stable** since June 2025 — through that growth, and alongside the official YouTrack MCP server. ## Business Outcomes - **Reduced friction to use YouTrack as a factual grounding layer** for both AI agents and humans — no more dead-end "AI can't see the tickets" investigations. - **Grounding you can rely on, not merely grounding you can reach.** Because oversized documents are read navigably instead of cut down to fit, and because requests that would come back plausible-but-wrong are refused rather than answered, the failure mode an assistant produces is a clear question instead of a confident mistake. - **AI that can act, not just read.** With personal-token authentication, assistants file, update, and comment on work as the real person, so AI-assisted workflows can close the loop inside YouTrack instead of handing the human a draft to paste back. - **Faster, better-informed work** across analysts, PMs, and developers, because the AI tools they already use can now reach — and update — project history directly. - **A reusable foundation for future YouTrack-aware AI workflows.** The server is designed for extension, so new agent use cases (automation, summarization, cross-system retrieval) can be added without rebuilding the integration layer. ## My Role As AI Product Manager at Spotware, I led the YouTrack MCP Server from concept to production — framing it as a system-level capability rather than a per-tool integration, defining the agent-friendly tool semantics, and making the product calls that shaped it: shipping a dedicated Deep Research endpoint so YouTrack could back ChatGPT Company Knowledge; moving to a personal-token-first model so the server could serve many users as themselves while still reaching across teams; insisting that an oversized document be made navigable rather than quietly cut down to size; treating what an assistant does when it fails as a product surface in its own right rather than an error-handling detail; and — once JetBrains released its own remote MCP server — deciding to keep and keep investing in ours on the strength of the specific capabilities our workflows still depend on. For the broader role context, see [AI Product Manager at Spotware](/experience/ai-product-manager-at-spotware/). ## Site index - [llms.txt](https://www.alexfeel.info/llms.txt) - [Complete index](https://www.alexfeel.info/llms-index.txt)