Connecting Your AI Agent to Atlassian’s Teamwork Graph: A Practical How‑To

By ● min read

Introduction

Atlassian has opened its Teamwork Graph—a living map of over 150 billion objects and relationships across Jira, Confluence, Jira Service Management, and dozens of connected SaaS tools—to any MCP-compliant agent. This means developers using Claude Code, IDE copilots, or other third-party agents can now query the same rich context that powers Atlassian’s own Rovo platform. By leveraging the graph’s built-in reasoning, you replace messy RAG dumps with precise, multi-hop traversals that keep context windows clean and your agent’s intelligence focused where it matters.

This guide walks you through the steps to connect your MCP-compliant agent to the Teamwork Graph, from setting up the required tools to executing your first Cipher query.

What You Need

• An active Atlassian account with access to Jira, Confluence, or Jira Service Management (any tier).
• An MCP-compliant agent (e.g., Claude Code, VS Code Copilot, or a custom agent).
• Basic familiarity with command-line interfaces and MCP concepts.
• A modern web browser (for testing with Rovo Chat if desired).

Step‑by‑Step Guide

Step 1: Enable MCP Server Access in Your Atlassian Instance

Before any agent can talk to the graph, your Atlassian organization must allow MCP server connections. This is a one-time setup typically done by an admin.

1. Log into your Atlassian admin console (admin.atlassian.com).
2. Navigate to Products > Data Management > Integrations.
3. Enable MCP Server Access under the “Teamwork Graph” section.
4. Generate an API token that your agent will use for authentication.

Step 2: Install and Configure the Teamwork Graph CLI Tool

Atlassian provides a command-line tool (in open beta) to interact with the graph directly. You’ll need it to test queries and to feed your agent with context.

1. Download the CLI from the official Teamwork Graph website (teamworkgraph.com).
2. Install it using your OS package manager or by extracting the binary into a directory in your PATH.
3. Run twg configure and paste the API token you generated in Step 1.
4. Verify connectivity with twg status – you should see a confirmation that the graph is reachable.

Step 3: Point Your MCP Agent to the Teamwork Graph Server

Now you tell your agent (e.g., Claude Code) to use Atlassian’s MCP server as a context source.

1. Open your agent’s configuration file (for Claude Code it’s claude_desktop_config.json).
2. Add a new MCP server entry with the URL: https://mcp.atlassian.com/v1 and include your API token as a bearer token.
3. Reload the agent or restart it so the new server is recognized.
4. Test the connection by asking your agent a simple question like “How many open Jira issues are assigned to me?” – if it works, the agent will query the graph.

Step 4: Write Your First Cipher Query for Multi‑Hop Traversal

The Teamwork Graph uses a query language called Cipher (not to be confused with Cypher). Rather than dumping raw text, you tell the agent to traverse relationships across objects.

1. Open the CLI tool and try a basic Cipher query: twg query "MATCH (p:Person)-[:WORKS_ON]->(j:JiraTicket) WHERE p.name = 'YourName' RETURN j.summary"
2. For a multi-hop example, find decisions linked to a project: MATCH (pr:Project)-[:HAS_DECISION]->(d:Decision) RETURN d.text
3. Incorporate these queries into your agent’s prompts. For instance, instruct Claude Code to “Use Cipher to find the latest Confluence page related to Project Alpha and summarize it.”
4. Your agent will run the Cipher query through the MCP server and return only the relevant context, keeping the context window lean.

Step 5: Test with Rovo Chat’s “Max” Mode (Optional)

If you want a quick no-code validation, use Atlassian’s Rovo Chat with the new Max mode, described as a “mini Claude Code” with Teamwork Graph context built in.

1. Open Rovo Chat in your browser (from your Atlassian product toolbar).
2. Switch to Max mode from the dropdown.
3. Ask a complex question that requires linking data across projects, e.g., “Show me all unresolved incidents in Service Management that are linked to Confluence documents I edited last week.”
4. Observe how the agent returns a concise answer without dumping raw text – this is the same intelligence your external agent will have.

Tips for Maximum Effectiveness

• Start simple: Begin with single-hop queries before trying multi-hop traversals. The graph is vast; let your agent “learn” the schema gradually.
• Monitor context usage: One advantage of Cipher is that it avoids stuffing the context window. Use your agent’s debug logs to see how many tokens are being consumed per query.
• Combine with RAG for hybrid calls: For unstructured data not yet in the graph, you can fall back to RAG. The Teamwork Graph excels at relationships, not raw text retrieval.
• Keep your token secure: Treat the API token like a password. Rotate it periodically and use environment variables instead of hardcoding.
• Explore the public site: The new teamworkgraph.com offers documentation, sample queries, and a sandbox for testing Cipher syntax.

By following these steps, you’ll effectively integrate external AI agents with Atlassian’s context layer—turning your enterprise data into a reasoning backbone rather than a dump of raw text.