Claude Code and Jira: should your agent use an MCP server or synced Markdown files?

Short answer:

• Use a live MCP server when your agent must act on Jira: move a ticket, add a comment, or check one issue's status right now.
• Use synced Markdown files when your agent must understand your work: search across many tickets and your docs at once, read them like code, and show you exactly which version it read.
• Most teams that use agents every day need both. Reading goes through the files, and acting goes through the live connection.

My AI agents (product, development, design and marketing) take their work from Jira every day. They connect to Jira live, through an MCP server. Their decisions and plans live as dated Markdown files in a repo.

I counted their tool calls over four weeks. They read Markdown files more than twice as often as they read Jira. And three of every four calls they made to Jira were writes: comments, status changes, new tickets.

I didn't plan that split. It happened because the two ways of connecting are good at different things. This note is what I learned about when to use which.

What is the difference between a Jira MCP server and synced Markdown files?

An MCP server answers your agent's questions by calling Jira live. Synced files are a copy of Jira, as Markdown, kept on disk and updated on a schedule.

• With MCP, every question becomes an API call: a search, then a fetch, then maybe another fetch. The agent sees what Jira returns at that moment, and nothing remains afterwards.
• With files, the agent reads Markdown the same way it reads your code: it greps, opens and compares. Each file says where it came from and when it was last checked.

When is a live Jira MCP server the better choice?

When the answer must be current to the minute, or when the agent has to change something.

• Acting: creating issues, comments, transitions. Files are read-only by nature.
• One precise lookup: "what's the status of this ticket right now?"
• Small or fast-moving projects, where an hour-old copy is already wrong.
• No setup on disk: nothing to store, nothing to keep in sync.

An honest objection I've seen from people who tried both: for simple questions, a live connection to their tools did about as well as a hand-built Markdown knowledge base. I believe it. If your questions are "find the ticket and tell me its status", MCP is enough.

When are synced Markdown files the better choice?

When the agent needs to understand many tickets together, alongside your docs and code, and you need to see what it read.

• Search across everything at once. Jira's search sees only Jira. Files from Jira sit next to your specs, decisions and code, and the agent searches all of them in one pass.
• Read like code. Agents are very good at grep, open, compare. A folder of Markdown is the format they handle best.
• Know what was true when. If the files live in git, every change has a date and a diff, so you can see what a ticket said last Tuesday. A live call shows only "now".
• Check what the agent saw. When an answer looks wrong, you can open the file it cited. With a live call there is nothing left to inspect.
• Fewer moving parts per question. No API calls in the middle of a task, and no rate limits.

What can go wrong with each one?

MCP fails loudly. Files fail quietly. That's the trade.

• Live MCP: a call fails, times out or hits a permission error, and the agent usually tells you. The risk is scope: if the token can write, the agent can write.
• Synced files: the copy drifts from Jira, and nothing tells you. Deleted tickets stay, a sync stops but reports success, or the "last synced" time lies. I wrote about the ways Markdown knowledge bases go stale. The fix isn't "sync more often". It's a sync that tells the truth about each source.

What about permissions?

Both inherit what the Jira account can see. Files add one more question: who can open the folder.

• A copy on disk or in a repo is readable by anyone with access to that folder or repo. Choose it the way you'd choose who sees those Jira projects.
• With MCP, the question is what the token is allowed to do. For an agent that only needs to read, a read-only setup is the safer default.

How do you use both?

Let the agent read from files and act through MCP.

1. Sync the Jira projects your agents need into a folder (or a repo), next to your docs.
2. Point the agent at that folder for search and context: "read the related tickets and the spec before you plan".
3. Keep a live MCP connection for actions and for "right now" checks.
4. Check the sync's status per source, not overall, so you notice when the copy has stopped.

How does Markdown Pipeline do this?

I built Markdown Pipeline for the file side. Today it covers Jira Cloud and local folders, on Linux, in early access.

• It writes each Jira issue as a Markdown file with a provenance block (where it came from), into a folder or a GitHub repo you choose.
• It only reads. It uses your own Jira account and API token, so the files hold only what your account can see. It never changes anything in Jira.
• Deletions are picked up on the hourly background check, and big deletions stop and ask first.
• It includes a local MCP server for the files, so Claude Code or Codex can search, read and list them, and ask what changed recently. It doesn't write to Jira, so keep your Jira MCP server for that.

Install it and start with the built-in sample data. No sign-in needed.

Do you use MCP, files, or both? Tell me what made you choose.