Let the agent do the typing: connect Jira and Confluence to your AI assistant
Most Product Owners and Product Managers don't lose time on decisions. They lose it on clicks: creating epics, splitting features into stories, copying acceptance criteria, updating Confluence pages, and preparing the backlog before PI Planning.
In an earlier LinkedIn post I shared the short version of a small hack: connect an AI agent to your backlog tools and let it draft while you decide. A few people asked how to actually set it up, and whether it's safe for company data. This post is my attempt at a complete, honest answer. It's what worked for me; your company's policies come first.
All config files from this post are also in a small companion repository you can copy from: github.com/Hemanthkolli/jira-confluence-mcp-guide.
The idea in one minute
- Create a personal token for Jira and Confluence.
- Run a small MCP server on your own machine. MCP (Model Context Protocol) is an open standard that lets AI assistants call tools; this server's tools are "search Jira", "read a page", "create an issue" and so on.
- Connect it to the assistant you already have in your IDE, for example GitHub Copilot in VS Code.
- Give it your planning input: meeting notes, a rough idea, last PI's objectives.
- Let it draft epics, stories, acceptance criteria and Confluence pages in your team's format. You review, adjust and decide.
The agent does the typing. You do the thinking.
How the pieces fit together
It helps to know exactly where things run before deciding whether it's acceptable for your organisation. There are four parts:
- Your IDE and its AI assistant. It decides which tool to call based on your prompt.
- The MCP server, a small Python program the IDE starts on your machine. It talks to the IDE over
stdio(standard input/output), so it doesn't listen on any network port. - Jira and Confluence. The MCP server calls their REST APIs over HTTPS with your token, so it can see and do exactly what you can. No more, no less.
- The AI model service. Your prompt, and the results of any tool calls, are sent to the model so it can reason about them.
Is our organisation's data safe?
Short answer: it can be, if you're honest about the one place data leaves the laptop, and you put a few controls in place. Here is how I think about it.
What stays on your machine
- The token. It's only read by the local MCP server. It's never sent to the AI model.
- The connection to Jira and Confluence. It goes directly from your laptop to your company's instance. There's no third-party relay or hosted connector in between.
- Everything the assistant didn't fetch. The server doesn't sync or index your Jira. It only calls the API when the assistant asks for something specific.
What does leave your machine
Be clear about this with your team and security colleagues: when the assistant reads an issue or a page, that text becomes part of the conversation and is sent to the AI model service. That's how the model can summarise or rewrite it.
So the real question is not "does data leave?" but "is the AI service we use approved for this data?" Some things to check:
- Use the company-approved assistant. With GitHub Copilot Business or Enterprise, GitHub states that your prompts and code are not used to train its models; check your organisation's agreement and data-retention settings for the details. A personal or free plan usually comes with different terms.
- Data classification. Don't point the agent at spaces or projects with data your company classifies as confidential or restricted (HR, legal, customer personal data) unless that's explicitly allowed.
- If nothing may leave at all, use a model your company hosts, or a local model your IDE supports. The MCP setup in this post stays the same; only the model endpoint changes.
Controls that make this safer
| Risk | Control | Where |
|---|---|---|
| The agent changes or deletes things | READ_ONLY_MODE=true to start; turn writes on later, per project | MCP server |
| Too much data in reach | JIRA_PROJECTS_FILTER, CONFLUENCE_SPACES_FILTER, TOOLSETS=default | MCP server |
| Leaked or long-lived token | Short expiry, never in Git, kept in a keychain or prompted by the IDE | Atlassian + your machine |
| The agent acts without asking | Keep tool confirmation on; never auto-approve write tools | IDE |
| Prompt injection: a ticket containing text like "ignore previous instructions…" | Read-only by default, human review before every write, filters on projects | You + MCP server |
| Unapproved tools in use | Admins can enable or disable MCP for Copilot through organisation policy | GitHub org settings |
| "Who changed this?" | Every change is made as your user, so Jira history and audit logs show it like any other change | Jira / Confluence |
One more honest note: mcp-atlassian, the server I use here, is a popular open-source
project (MIT licence), not an official Atlassian product. Read its code or ask your
security team to review it, and pin the version you approved (I show how below). Atlassian also
offers an official remote MCP server for Cloud that uses OAuth instead of tokens; it's worth
comparing if you're on Cloud.
Step 1: Create a token in Jira and Confluence
Which kind of token you need depends on how your company runs Atlassian. If your Jira address ends in atlassian.net, you're on Cloud. Otherwise it's most likely Data Center (or the older Server).
Cloud
On Cloud, one API token covers both Jira and Confluence.
- Open id.atlassian.com → Security → API tokens.
- Click Create API token.
- Give it a clear name, e.g.
mcp-laptop-2026, and pick the shortest expiry you can live with. - Click Create, then Copy. You won't see the token again.
You'll also need the email address of your Atlassian account (used as the username), plus these URLs:
JIRA_URL=https://your-company.atlassian.net
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
Atlassian also offers "API token with scopes". The MCP server's documentation uses the classic API token for Cloud, so check its docs before using a scoped one.
Data Center / Server
On Data Center you create a Personal Access Token (PAT) in each product separately. PATs are available from Jira 8.14 and Confluence 7.9 onwards.
- In Jira, click your avatar (top right) → Profile → Personal Access Tokens.
- Click Create token, give it a name and set Automatic expiry (for example 30 or 90 days).
- Click Create and copy the token right away.
- Repeat the same steps in Confluence: avatar → Settings or Profile → Personal Access Tokens.
JIRA_URL=https://jira.your-company.com
CONFLUENCE_URL=https://confluence.your-company.com
Some companies turn PATs off or limit their lifetime. If you don't see the menu, ask your Atlassian admins. Don't try to work around it.
Good habits for any token: one token per machine and purpose, a short expiry, never in a Git repository, never pasted into a chat or a ticket, and revoke it on the same page the moment you don't need it.
Step 2: Install the MCP server without sudo
The server is a Python package. The easiest way to run it is with
uv, a small tool that installs into your home folder,
downloads its own Python if needed, and doesn't need admin rights. Its uvx command runs a package
in an isolated environment.
Linux
Installs to ~/.local/bin, no sudo:
curl -LsSf https://astral.sh/uv/install.sh | sh
If your company doesn't allow piping scripts into a shell, use pip in user mode instead:
python3 -m pip install --user uv
Open a new terminal, then check it works and pin the version you've approved:
uvx mcp-atlassian@0.24.7 --help
macOS
With Homebrew (no sudo):
brew install uv
Without Homebrew, the installer puts it in ~/.local/bin:
curl -LsSf https://astral.sh/uv/install.sh | sh
Open a new terminal, then check it works and pin the version you've approved:
uvx mcp-atlassian@0.24.7 --help
Windows
In PowerShell (as your normal user, not "Run as administrator"). It installs to %USERPROFILE%\.local\bin:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Or with winget, which installs per user:
winget install --id=astral-sh.uv -e
Open a new terminal, then check it works and pin the version you've approved:
uvx mcp-atlassian@0.24.7 --help
Why pin the version? uvx mcp-atlassian without a version always fetches the latest release. Pinning means a new release only reaches your machine after you've decided to upgrade. That's a small but real supply-chain safeguard. 0.24.7 was current when I wrote this; check PyPI for newer versions.
Behind a corporate proxy? Set HTTPS_PROXY in the same env block as the other settings. Company root certificates in your operating system's trust store are picked up automatically.
Step 3: Keep the token out of config files
Many examples online put the token straight into a JSON file. That's how tokens end up in Git history and screenshots. Better options, from my favourite down:
- Let the IDE ask for it. VS Code and Visual Studio can prompt for the token once and store it encrypted. That's shown in step 4.
- Read it from your keychain at runtime. The server supports
*_COMMANDvariables: instead of the token, you give it a command that prints the token. - A private env file in your home folder, readable only by you, and never inside a project folder.
Linux
With the GNOME keyring (secret-tool), store the token once. It asks for the value, so it never ends up in your shell history:
secret-tool store --label="Jira token" service mcp-atlassian account jira
Then, in the server's env, use the command instead of the token:
"JIRA_API_TOKEN_COMMAND": "secret-tool lookup service mcp-atlassian account jira"
If secret-tool isn't installed and you can't install it, use an env file only you can read:
mkdir -p ~/.config/mcp-atlassian
touch ~/.config/mcp-atlassian/env && chmod 600 ~/.config/mcp-atlassian/env
macOS
macOS has a keychain command built in. Store the token once; the trailing -w makes it prompt for the value:
security add-generic-password -a "$USER" -s mcp-atlassian-jira -w
Then, in the server's env:
"JIRA_API_TOKEN_COMMAND": "security find-generic-password -s mcp-atlassian-jira -w"
Windows
The simplest secure option on Windows is to let VS Code or Visual Studio prompt for the token (step 4). If you use a password manager with a CLI, the command approach works too, for example with 1Password:
"JIRA_API_TOKEN_COMMAND": "op read \"op://Work/Jira token/credential\""
On Windows, use double quotes inside the command. For a .bat or PowerShell helper, prefix it with cmd /c or powershell -NoProfile -Command.
For Data Center, the variables are named JIRA_PERSONAL_TOKEN_COMMAND and CONFLUENCE_PERSONAL_TOKEN_COMMAND.
Step 4: Connect your IDE
Every IDE uses the same server and the same settings; only the config file differs.
The examples use Cloud with read-only mode and a project filter. For Data Center, replace
JIRA_USERNAME + JIRA_API_TOKEN with JIRA_PERSONAL_TOKEN (same for Confluence).
VS Code + GitHub Copilot
- Open the Command Palette and run MCP: Open User Configuration (all projects), or create
.vscode/mcp.jsonin a project. - Paste this. The
inputsblock makes VS Code ask for the token once and store it encrypted, so it's never in the file:
{
"inputs": [
{
"id": "atlassian-token",
"type": "promptString",
"description": "Atlassian API token",
"password": true
}
],
"servers": {
"atlassian": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-atlassian@0.24.7"],
"env": {
"JIRA_URL": "https://your-company.atlassian.net",
"JIRA_USERNAME": "you@your-company.com",
"JIRA_API_TOKEN": "${input:atlassian-token}",
"CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
"CONFLUENCE_USERNAME": "you@your-company.com",
"CONFLUENCE_API_TOKEN": "${input:atlassian-token}",
"READ_ONLY_MODE": "true",
"TOOLSETS": "default",
"JIRA_PROJECTS_FILTER": "ABC",
"CONFLUENCE_SPACES_FILTER": "TEAM"
}
}
}
}
- Click Start above the server name in the file, or run MCP: List Servers. VS Code asks for the token the first time.
- Open Copilot Chat, switch the mode to Agent, and click the tools icon. You should see the Jira and Confluence tools.
With Copilot Business or Enterprise, an organisation admin has to allow MCP servers in Copilot. If the tools don't appear, that policy is the first thing to check.
Visual Studio
Visual Studio 2022 (17.14 and later) supports MCP servers in Copilot's agent mode, using the same servers format as VS Code.
- Create
%USERPROFILE%\.mcp.jsonfor all solutions, or.mcp.jsonnext to your solution file for one solution. - Paste the same
inputsandserversblock as in the VS Code tab. - Open Copilot Chat, select Agent mode, and enable the Atlassian tools in the tools picker.
If Visual Studio can't find uvx, use the full path: C:\\Users\\<you>\\.local\\bin\\uvx.exe. Remember the double backslashes in JSON.
JetBrains (IntelliJ, PyCharm, Rider, …)
There are two common routes:
- JetBrains AI Assistant: Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add, then paste the JSON below.
- GitHub Copilot plugin: in Copilot Chat, switch to Agent mode, click the tools icon → Add more tools…. This opens Copilot's
mcp.json, which uses the sameserversformat as VS Code.
{
"mcpServers": {
"atlassian": {
"command": "uvx",
"args": ["mcp-atlassian@0.24.7"],
"env": {
"JIRA_URL": "https://your-company.atlassian.net",
"JIRA_USERNAME": "you@your-company.com",
"JIRA_API_TOKEN_COMMAND": "security find-generic-password -s mcp-atlassian-jira -w",
"READ_ONLY_MODE": "true",
"TOOLSETS": "default",
"JIRA_PROJECTS_FILTER": "ABC"
}
}
}
}
This example reads the token from the macOS keychain (step 3). Use the Linux or Windows command from step 3 on those systems.
Cursor
Create ~/.cursor/mcp.json for all projects, or .cursor/mcp.json in one project. Cursor uses the mcpServers format, the same as the JetBrains tab. Then enable the server under Settings → MCP.
Cursor has no password prompt like VS Code, so use the keychain command from step 3 rather than writing the token into the file.
Claude Code
One command, stored in your user settings and available in every project:
claude mcp add atlassian --scope user \
-e JIRA_URL=https://your-company.atlassian.net \
-e JIRA_USERNAME=you@your-company.com \
-e "JIRA_API_TOKEN_COMMAND=security find-generic-password -s mcp-atlassian-jira -w" \
-e READ_ONLY_MODE=true -e TOOLSETS=default -e JIRA_PROJECTS_FILTER=ABC \
-- uvx mcp-atlassian@0.24.7
Run claude mcp list to check it's connected. Claude Code asks before every tool call unless you allow it, so leave write tools on "ask".
Step 5: First test, read-only
Start with questions that only read. If these work, the connection, token and filters are right:
- "List the open stories in project ABC assigned to me, with status and story points."
- "Summarise the Confluence page 'Team working agreement' in five bullet points."
- "Which epics in ABC have no stories yet?"
Also check the filters work. Ask about a project that's not in JIRA_PROJECTS_FILTER; the agent shouldn't be able to see it.
Worked example: PI Planning prep with GitHub Copilot
Here's the flow I use in VS Code with Copilot in agent mode. Nothing is written to Jira until the last step, and only after I've read the drafts.
1. Teach it your conventions once
Create a file in your workspace, for example backlog-conventions.md:
# Backlog conventions (team ABC)
- Story title: "As a <role>, I want <goal>" (max 80 characters)
- Description sections: Context, Scope, Out of scope
- Acceptance criteria: Given / When / Then, 3 to 6 per story
- Labels: pi-2027-1, plus one of: backend, frontend, platform
- Story points: leave empty; the team estimates in refinement
- Language: plain English, no internal code names
2. Ask for drafts, not actions
youRead #file:meeting-notes-2026-11-20.md and #file:backlog-conventions.md. Then look at the open epics in Jira project ABC. Draft one new epic and the stories needed for the "supplier onboarding" topic. Show me the drafts as Markdown. Don't create anything in Jira.
copilotCalls jira_search (read-only) and checks existing epics, then returns a Markdown draft: one epic, six stories, acceptance criteria in Given/When/Then, and a note that two of the stories overlap with the existing epic ABC-412.
3. Review and adjust like you would with a colleague
youMerge stories 3 and 4. Story 6 belongs in ABC-412, so move it there instead. Make the acceptance criteria of story 2 testable; "fast" isn't measurable.
4. Only then, let it create
Switch the server to allow writes (see the next section), then:
youCreate the epic and the five stories in ABC exactly as in the final draft. Link the stories to the epic. Then list the new issue keys.
copilotVS Code shows a confirmation for each jira_create_issue call with the exact fields. You click Continue only for the ones you've checked.
The same works for Confluence: "Draft the PI objectives page in the format of last PI's page, but don't publish it", then review, then create it.
Turning on writes, carefully
- Change
READ_ONLY_MODEto"false"only for the session where you create things, and set it back afterwards. - Keep
JIRA_PROJECTS_FILTERlimited to your own project, so a mistake can't reach other teams' boards. - For even tighter control, allow only the tools you need:
"ENABLED_TOOLS": "jira_search,jira_get_issue,jira_create_issue". - Never turn on "auto-approve" for write tools in your IDE. Reading each confirmation takes seconds; undoing 40 wrongly created issues doesn't.
Troubleshooting
- The IDE says
uvxis not found - IDEs started from a menu often don't see your terminal's
PATH. Use the full path:~/.local/bin/uvxon Linux and macOS (or/opt/homebrew/bin/uvxwith Homebrew), andC:\Users\<you>\.local\bin\uvx.exeon Windows. 401 Unauthorized- On Cloud, check you used your email as the username and an API token, not your password. On Data Center, use
JIRA_PERSONAL_TOKENand no username. Also check the token hasn't expired. - SSL or certificate errors
- Company root certificates from the OS trust store are used automatically. If it still fails, ask IT for the right CA bundle rather than turning verification off.
- The tools don't show up in Copilot
- Make sure you're in Agent mode, the server is started (MCP: List Servers), and your organisation allows MCP servers in Copilot.
- The agent sees too much or too little
- Check
JIRA_PROJECTS_FILTERandCONFLUENCE_SPACES_FILTER(comma-separated keys), and remember the token can only see what you can see.
Checklist
- The AI assistant is approved by my organisation for this kind of data
- Token has a short expiry and is stored in a keychain or IDE prompt, not in a file in Git
- MCP server version is pinned and reviewed
READ_ONLY_MODE=trueby default- Projects and spaces are filtered to what I actually need
- Tool confirmations are on in the IDE, and nothing is auto-approved for writes
- Conventions file written once, reused every time
- I review every draft before anything is created
I'm still learning what works best here, and tools in this space change quickly, so menu names may have moved by the time you read this. If something is out of date or you've found a better way, please tell me.
Practising what I preach: this post was drafted with AI from my own ideas and experience. The thinking is mine; the typing was shared.