Skip to content
AI agents & MCP

Connecting Claude Code to Your Project Management Tool With MCP

By Sebastiaan Jansen · · 9 min read

A claude code mcp server is a small program that lets Claude Code call your project tool, docs, or internal API through tools you define. You add it to project or user config, pass a token through the environment, and approve each call. After that, the agent can list tickets, read acceptance criteria, and plan work against the repo without anyone pasting a board into chat.

The server does not replace your tracker. It gives the coding agent a narrow, logged way to read, and sometimes write, the same records your team already uses.

What a Claude Code MCP server is for

Claude Code reads files and edits the repo. It does not know your sprint, your ticket IDs, or the comment where a customer described the bug. Pasting that context in by hand stops working as soon as the ticket changes or a second engineer asks the same question.

MCP (Model Context Protocol) is an open way for an assistant to call tools on a server you run. The spec lives at modelcontextprotocol.io. A server advertises tools, resources, and prompts. The client decides which calls to make, and in Claude Code you can require a human yes before any write.

For a project tool, the useful tools look like this:

  • List tickets assigned to me, or in this cycle, filtered by state.
  • Read one ticket, including description, acceptance criteria, and links.
  • Add a comment or move a state, only when a person has approved that call.
  • Search recent decisions so the agent does not reopen a closed debate.

Make read tools the default. Keep write tools few, clearly named, and easy to refuse. A server that can "update anything" will eventually close the wrong ticket.

If you want the protocol itself explained in plain language, start with What Is an MCP Server? A Plain Guide for Product and Engineering Teams. This article stays on the Claude Code side: config, scope, and a concrete tracker example.

How to add a claude code mcp server

Claude Code loads MCP servers from a project file and from your user config. For a team tracker, project scope is the right default: everyone who clones the repo gets the same server command, and secrets stay out of git.

A typical project file is .mcp.json at the repo root:

{
  "mcpServers": {
    "tracker": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/tracker-mcp"],
      "env": {
        "TRACKER_API_TOKEN": "${TRACKER_API_TOKEN}"
      }
    }
  }
}

With stdio, Claude Code starts the process and talks to it over stdin and stdout, which is the usual choice for a local tool. Remote HTTP or SSE suits a shared server your platform team already runs. Use whichever transport your server documents. Do not commit the token. ${TRACKER_API_TOKEN} should expand from the developer's environment or from a secret store your team already trusts.

You can also register the server from the terminal:

claude mcp add tracker -- npx -y @example/tracker-mcp

Run claude mcp list to check what loaded. If a server fails, Claude Code still starts, so you only notice when a tool is missing. Read the server's own logs before you change anything on the client side.

Project config versus user config

Scope Where it lives Use it for
Project .mcp.json in the repo The tracker, the repo host, team docs
User Your Claude Code user settings Personal notes, local databases, one-off experiments
Server admin A remote URL the whole company calls A vetted internal API with central auth

Project config belongs in code review. A tool that can post to customers or delete issues is a product change, and it should be reviewed like one. User config is fine for a scratch server but a bad place for a team workflow, because nobody else can reproduce the session. Restart after you edit the file, since a running conversation keeps the tool list it started with.

Permissions

Claude Code asks before it runs a tool unless you have allowed a pattern. Treat a write to the tracker like a shell command that pushes to production. Reads can be allowed more freely if the data is not customer-private. Keep "move ticket", "post comment", and "create issue" behind explicit approval, and name tools so the dialog is easy to read: tracker_add_comment is reviewable, tracker_sync is not.

Worked example: one ticket, one plan

This example uses a fake local package, @example/tracker-mcp, so you can see the shape without tying it to one vendor. If your tracker ships an official server, swap that in. Linear, Jira, GitHub Issues, and smaller tools differ in auth and field names, but the sequence below stays the same.

Setup: the repo has .mcp.json as above, and the developer exports TRACKER_API_TOKEN in their shell. The server exposes four tools: list_cycle_tickets, get_ticket, add_comment, and set_status. Only the first two are pre-approved.

The ask: an engineer tells Claude Code, "Plan T-184. Do not edit the tracker."

What the agent should do:

  1. Call get_ticket with T-184. The payload includes the title, the acceptance criteria, and a link to the design note.
  2. Call list_cycle_tickets with status in progress, but only if the ticket says it is blocked by another issue. Otherwise skip the extra call.
  3. Read the files named in the ticket and search the repo for the function the criteria mention.
  4. Reply with a short plan: files to touch, tests to add, and anything in the criteria the code cannot satisfy yet.
  5. Stop there. No comment, status change, or commit until the engineer says so.

A later, separate ask: "Post the plan as a comment on T-184." Claude Code shows the add_comment call with the ticket id and the body, and the engineer accepts or rejects it. The server writes one comment and leaves the column where it was.

The split is deliberate. A plan is cheap to retry, while a status change tells the rest of the company the work is in review. Those deserve different permissions, even when the same claude code mcp server can do both. If the official server ships dozens of tools, turn off the ones you do not want, because a shorter list is easier to approve.

What to expose, and what to leave out

A good server maps the questions engineers already ask the tracker, and not much more.

Expose:

  • Identity of the caller, so comments show a person instead of a shared bot with no owner.
  • Ticket id, title, state, assignee, cycle, and the description in plain text.
  • Acceptance criteria and links, even if you drop HTML styling.
  • A search that takes a query and a project, with a hard limit (20 is enough).

Leave these out until you have a reason and a review: bulk edit and bulk close, permission or billing changes, anything that emails a customer, and raw SQL against the tracker database. Call the API instead, because the API has the audit log.

Describe the side effect on every tool, for example "Reads one ticket" or "Posts a comment and does not change status." Cap list results so they return ids, titles, and states, and let get_ticket fetch the body. If you dump a full cycle into context, the one ticket that matters gets lost.

When a script is enough

Most teams already have scripts that curl the tracker. An MCP server Claude Code can call can sit in front of those same APIs and still be worth it: the tool list is visible, ticket ids are real parameters, and a 401 comes back as a result the agent can report. Another coding agent can mount the same server later. AI Coding Agents: How Teams Use Them Without Losing Control covers who may merge and where a human still signs off.

For a one-off migration, write a script and delete it afterward. MCP pays off when the question repeats: what is in this ticket, and does the branch match it?

Where the project tool still decides

Connecting Claude Code will not fix a vague board. If titles say "quick fix" and the acceptance criteria live in a private thread, the agent will confidently plan the wrong change. The server can only return what the ticket contains.

Keep the tracker as the source of truth for priority, owner, and done. Let the agent propose a plan and a diff, and have a person move the ticket once the review has actually happened.

Keep one outcome per ticket. Put acceptance criteria in the ticket, not only in a call recording, and put the ticket id in the branch name. Letting the agent set "In progress" on request is reasonable. "Done" stays with the reviewer.

AI Project Management: What Actually Works in 2026 goes deeper on what to automate and what to leave on the board. In short, agents are good at reading a well-formed ticket and drafting the change, and poor at deciding whether the ticket should exist.

Claude Code for Teams: Planning, Tickets and Shared Context walks through how a team shares that planning context so the next session does not start from zero.

Some platforms ship the tracker and the agent connection together, and Falrow is one of them. Requests from Slack, calls, and error reports become tickets. Claude Code and Codex plan from the git repository through its MCP tools, under the team's workflow rules, with version-checked writes. The agent connection and the MCP tool catalogue pages list those tools. Your tracker's own server follows the same pattern.

A vendor server means less code to maintain, but it may lag behind the fields you care about. A local server is yours to change and yours to secure. Store tokens in the environment or a secret manager, scope them to the projects the team works in, and rotate them when someone leaves.

A checklist before the team relies on it

Run through this once on a real ticket, with a second person watching the approvals.

  1. The server starts from a clean shell with only the documented env vars.
  2. A read tool returns one known ticket, and a missing id returns a clean error.
  3. A write tool does nothing until the approval dialog shows the ticket id and the exact change.
  4. Secrets are absent from .mcp.json, from the repo, and from the tool output.
  5. The tool list in claude mcp list matches what code review approved, with extra tools turned off.
  6. A teammate who did not write the server can repeat steps 2 and 3 from the README.

If step 6 fails, the setup is still a personal hack, and it should not be updating production tickets.

FAQ

Does Claude Code need a separate MCP server for every tool?

No. One server can expose several tools for one system, which is what you want for a tracker. Add a second server when the system is different: chat, errors, docs, or the git host. Too many servers slow startup and clutter the tool list, while too few servers with vague mega-tools make approvals meaningless. Group by system and keep each tool single-purpose.

Where should the claude code mcp config live?

For a shared tracker, put it in the project .mcp.json and review it like code. Personal experiments go in user settings. Keep tokens in the environment, not in the file. After any edit, restart Claude Code and confirm the server with claude mcp list before you trust a planning session.

Can the agent update tickets without asking?

Only if you allow those tools in permissions. Leave status changes and comments on an explicit prompt. Reads can be looser when the data is internal and the list size is capped. Review the permission file the way you would review a deploy key, because a config that auto-approves every tool will eventually write something nobody asked for.

What if our tracker has no official server?

Write a thin local server that calls the tracker's API, or use a community server once you have read which endpoints it hits. Start with get and list, and add one write tool after the read path has been stable for a while. Document the token scope, the rate limit, and the command Claude Code should run. An official server is less work when one exists, and a small private one is enough when it does not.

More on ai agents & mcp