atlassian-mcp-server

Teamwork Graph context

This is the shared method every skill in this repo uses to gather context and deliver its result. A skill loads it first, then adds what’s specific to its job: the anchor, the sources it needs, what the artifact shows and when to stop. Where a skill and this file disagree, the skill wins.

Companion skills mentioned as alternatives or next steps are optional. Check that a suggested skill is installed before offering its slash command. If it is unavailable, describe the next step in ordinary language and use the current host’s available capabilities.

Principles

  1. Use the graph to discover and the records to confirm. Start from one object in Teamwork Graph and walk its relationships. That’s how you find connected work, docs and conversations across tools. For structured facts (dependencies and their direction, linked projects, owners, teams, statuses, dates), the product record is the source of truth. Cross-check, and say when the graph and the record disagree. “What the graph doesn’t tell you” lists the known gaps.
  2. Keep sensitive content out. Search can return HR, performance, legal and other confidential documents even for unrelated queries. Never quote, summarise, cite or title them anywhere. See “Sensitive content”.
  3. Third-party sources are first-class. A Slack thread, a Google Doc or a Zendesk ticket counts as much as a Confluence page or a Jira work item. Never call them fallbacks or rank them below Atlassian sources. Label where each fact came from; don’t rank sources by vendor.
  4. Linked and found are different. A relationship stored in the graph or a product record is confirmed. A search hit that looks related is inferred. Keep them apart in the reasoning and in the artifact.
  5. Never invent. No made-up titles, owners, dates, statuses, quotes or numbers. If something can’t be confirmed, say so.
  6. Say what’s missing. A source that wasn’t connected, a search that returned nothing, a record that doesn’t exist and a check you couldn’t run are all results. Show them.
  7. Read-only by default. Only write (create, edit, link, comment, post) when the skill’s job is the write or the user asks, and confirm first.
  8. Fall back on vendor connectors for what the graph can’t do. When Teamwork Graph and the Atlassian product tools can’t answer something a skill needs (a day’s meetings, recent email, a full Slack thread), use the vendor’s own connector if the client has one. See “Vendor connectors”. This is about which tool to call, not how much a source counts: a fact read through a vendor connector counts the same as one from the graph.

Sensitive content

Searches surface whatever the user can see, and that includes documents nobody wants in a status report. This rule overrides every skill.

Tools

These are the operation names on version 2 of the Atlassian Rovo MCP server, the only version these skills support (version 1 is being deprecated). Clients prefix them with the connector’s name (for example mcp__atlassian__search). Connect it using the current agent host’s documented MCP setup. Access to tools in a conversation does not imply access from an artifact; check the host’s live-artifact capabilities separately (see “Live artifact”).

Teamwork Graph tools

Tool Use it to Know this
getGraphContext Walk from one object to everything linked to it, across Atlassian and connected tools, in one call. Filter with relationshipTypes, targetObjectTypes and timeRange. Direction is only in the relationship name, and same-type names don’t all read the same way. Some links are missing or one-sided, and Atlas project and goal keys don’t resolve. See “What the graph doesn’t tell you”.
getGraphObject Read full detail for up to 25 objects at once by ARI or URL. Full for Atlassian objects and Google Drive docs. Often empty (raw: {}) for GitHub, and refused for Slack. Bitbucket pull requests hydrate when passed by the graph ARI (state, approvals, description cut at about 1,000 characters), though bitbucket.org URLs don’t resolve. Confluence pages come back as raw ADF, which can be huge: use getConfluenceContent instead.
search Find things the graph hasn’t linked. See “Searching”.
getWorkActivity What a person or up to 10 people did, were assigned or were mentioned in, across Jira, PRs, docs, goals, calendar and video, over a time window. Use countsOnly when you only need the volume. topic can’t be combined with identifiers. With identifiers, trust each item’s ok over the batch summary, which can count partial coverage as a failure.
getWorkPortfolio Projects, goals and focus areas for people, with status. Large by default, because it includes direct reports. Pass includeDirectReports: false unless you need the org, and use kinds, view: compact and limitPerCollection. includeInferredProjects can return SOURCE_FAILURE. If it does, record the gap and move on.
getPeopleInfo Profiles, managers and direct reports. manager: true gives the escalation contact in the same call. Profiles carry a department but no team: take a person’s team from the project or work record that names them.
getCollaborators Who someone works with most.  
searchCode, getCodeFile, scanCodeRepo, listCodeDirectory Search code across connected Bitbucket and GitHub repos (mode hybrid, semantic or lexical, filtered by namespace, repo, path, language), then read a file, list a repo’s paths or browse a directory at a commit. Reached through discover and run with executeRead, only when code-search is in the site’s products list. Pass a result’s own workspace, repo, path and version (as commitHash) to the reads, never the search filter. Results are noisy and getCodeFile has no line numbers: see “Code and repositories”.

Product tools

Use these for structured facts, and for detail the graph doesn’t carry:

Need Tool
A goal’s projects, sub-goals, metric targets, updates and highlights getGoal
A project’s dependencies, links, teams, updates and highlights getProject, getProjectUpdate
Jira issue links with direction getJiraIssue with view: evidence (issuelinks[].inwardIssue and outwardIssue)
A Jira issue’s web links to pages and URLs listJiraIssueRemoteIssueLinks
When a Jira field changed (status, assignee) listJiraIssueChangelogs
Lists of Jira work by structured criteria searchJiraIssuesUsingJql
A Confluence page body getConfluenceContent with content_format: markdown and detail: full (the default is a short excerpt)
A Loom transcript or AI action items getLoomVideo
Release approvers, capacity, teams getJiraProjectVersions, getCapacityPlanAllocations, searchTeams
A board’s sprints and columns, and a sprint’s issues getJiraBoardSprintData, getJiraBoardConfig (through discover)

Relationship names

getGraphContext returns and filters on underscore names. addGraphContext takes hyphenated names. Names seen so far:

Read with getGraphContext Write with addGraphContext
jira_work_item_blocks_jira_work_item, jira_work_item_is_blocked_by_jira_work_item jira-work-item-blocks-jira-work-item
jira_work_item_tracks_atlassian_project jira-work-item-tracks-atlassian-project
jira_work_item_contributes_to_atlassian_goal jira-work-item-contributes-to-atlassian-goal
jira_work_item_has_child_jira_work_item, jira_work_item_has_parent_jira_work_item (use the issue’s parent field)
jira_work_item_links_jira_work_item_remote_link jira-work-item-links-jira-work-item-remote-link
atlassian_project_depends_on_atlassian_project, atlassian_project_links_atlassian_project (use Projects)
atlassian_project_contributes_to_atlassian_goal (use addConnectionsToGoals with type PROJECT)
atlassian_project_has_atlassian_project_update  
atlassian_user_owns_atlassian_project, atlassian_user_contributes_to_atlassian_project  

Call getGraphContext with detailLevel: summary first to see which relationship types an object actually has, then filter the full call to the ones you need.

Vendor connectors

The client may also have connectors from the vendors themselves, such as Google Calendar, Gmail, Google Drive, Slack, GitHub, Microsoft 365 (Outlook, Teams, OneDrive) or Zoom. They show up in the session’s tool list under the app’s name. Teamwork Graph comes first, because it connects tools and a vendor connector only sees its own app. Always run the graph’s own search or read before reaching for a connector, even for an app that has one. Use a vendor connector only to fill a gap the graph has, and say in the footer which gap it filled:

Gap in Teamwork Graph Use the vendor connector to
Lists by time. getWorkActivity windows on when a relationship last changed, recurring meetings have no daily instances, and search has no date filter. List a day’s calendar events. For email and chat, filter graph search results by lastModified first, and use the connector’s date operators (such as newer_than:1d or after:2026-10-18) only when that came back empty or too thin to trust.
Third-party objects that won’t hydrate (Slack messages left out of getGraphObject, GitHub raw: {}, Drive docs with no body). Read the full thread, replies, pull request body and reviews, or doc, instead of settling for the search snippet.
Facts only the vendor holds. Read RSVPs, recurrence and attendee lists for meetings, whole email threads, and file revision history.

Setup

Fetch in parallel

Most of a run’s time goes on calls made one after another. Before each step, list the calls whose inputs you already have, and send them together in one turn: lookups for each person, each candidate video or doc, each search phrasing, and reads of goals and projects already found. Wait only for the calls the next step needs. Calls that don’t depend on each other can run together even when they sit in different steps of a skill.

Searching

Dating events in a window

For a skill that covers a window (“since the last update”, “while I was away”), each item gets one event time, the moment the thing happened, from this table. An item is in the window only if its event time is.

Source Event time
Jira status, assignee, due date or priority change The changelog entry’s created
Jira work item created or resolved created or resolutiondate
Comment (Jira, Confluence, Loom) The comment’s created time
Confluence page edit The createdAt of the version that made the change. When a diff spans many versions and the change can’t be pinned to one, show the range (“edited Oct 7 to Oct 21”)
Project or goal update, or highlight Its creationDate
Pull request mergedAt, or createdAt for a new one
Meeting Its start time
Loom recording Its creation time
Third-party search result lastModified, which is the last edit, so it can say “updated” but never “new”

What the graph doesn’t tell you

These gaps showed up on real data. Work around them as described, and say in the footer when one affected the result.

The context loop

1. Resolve the anchor

Every skill starts from one object, or a small set of the same kind. Work out what the user gave you, resolve it, and confirm it’s the right one before going further.

The user gives you objectType Resolve with
A meeting or calendar invite ExternalCalendarEvent (LoomMeeting, LoomMeetingRecurrence for Loom) The calendar’s own connector (see “Calendars”). In the graph, getWorkActivity with types: calendar and activity: all
A Jira work item, release or project JiraWorkItem, JiraVersion, JiraSpace The key or URL
A Jira sprint None in the graph (see “Sprints”) getJiraBoardSprintData with the board and the sprint’s name or ID
An Atlassian project or goal AtlassianProject, AtlassianGoal getProject or getGoal, then the returned ARI or URL
A focus area FocusFocusArea getFocusArea
A Confluence page, whiteboard or database ConfluencePage, ConfluenceWhiteboard, ConfluenceDatabase The URL
A person or team AtlassianUser, AtlassianTeam getPeopleInfo, searchTeams
A service or component CompassComponent, ExternalService The URL or ARI
A pull request, repo, deployment or design ExternalPullRequest, ExternalRepository, ExternalDeployment, ExternalDesign The URL. A repository links only to its pull requests, commits and branches (see “Code and repositories”), so start from its code with code search to find what it does or who owns it
A Slack or Teams thread ExternalConversation The URL (may not resolve; see “Hydrate”)
A Google Drive, SharePoint or Dropbox doc ExternalDocument The URL
A customer account ExternalOrganisation An ARI from a result only
A CMDB object AssetsObject The key or URL
A Loom video LoomVideo The share URL

2. Expand from the anchor

3. Sweep for what isn’t linked

Much of the useful context, such as a decision in Slack or a customer complaint in Zendesk, was never linked to anything. After expanding, run 2 to 4 searches as “Searching” describes. Keep a hit only if it’s clearly about the anchor (same names, keys, people or dates), and mark it as found by search.

4. Hydrate

5. Bring in people

6. When to stop

Connector coverage

Skills get better with more of the customer’s tools connected, so be explicit about coverage.

Atlassian apps on the site

Don’t assume a site has every Atlassian app. Check before gathering:

Third-party apps

Labelling sources

Copy

Writes

Publishing

Follow the calling skill’s delivery mode. A skill that explicitly selects “Answer-first delivery” uses the flow below. Other skills keep their existing artifact flow: build the static artifact unless a live one is available and the skill’s “When live” section says what it adds. Load atlassian-design only when building a report or artifact.

Answer-first delivery (only when the calling skill selects it)

  1. Give the result in the conversation first. Use the calling skill’s assessment, ranking, row limits and content requirements. Cite evidence with ordinary Markdown links, retain Recorded, Proposed and Found by search labels as plain text where required, and include coverage, dates, caps and gaps in a Sources and limitations section. Do not load design guidance, write report data, run a renderer or create an artifact for this initial answer.
  2. Offer the existing HTML report as an optional export. Ask whether the user wants it and wait for their answer. An ordinary invocation of the skill is not a request for a file. An explicit request for an HTML report, file export or publication already authorises the corresponding report build; do not ask again. Reuse the findings already gathered, and keep all evidence labels and limitations. If new evidence is needed, stay within the skill’s budgets and explain what changed.
  3. Check Atlassian Artifacts availability before offering publication. Reuse the selected site’s products list from getAccessibleAtlassianResources; do not choose another site silently. If artifacts is absent, skip publication tools and offers. If it is present, confirm that createArtifactsUpload and publishArtifact are available in this session, through discover if necessary, without creating an upload as a test. If availability cannot be confirmed, say so when relevant and hand over the report file.
  4. Keep export and publication separate. Agreement to export is not agreement to publish. When the service is confirmed available, offer a private, read-only Atlassian Artifact with the calling skill’s name and description. Publish only on an explicit request, using the static publishing steps below. If the user already requested export and publication, complete both without asking again. An unavailable publishing service never blocks the answer or local HTML export.
  5. Keep other writes independent. Skipping export does not authorise or cancel other writes the calling skill offers. Follow its conditions and confirmations. Share a published artifact only on request, with the people the user approves.

Static artifact (the default)

Don’t publish by default. Publishing is a write, so hand over the file and offer to publish a private, read-only copy as an Atlassian Artifact. Publish only when the user says yes, or has already asked for it in this request.

  1. Build one self-contained HTML file. Inline all CSS, JavaScript and images, and use no external files. Don’t use localStorage, sessionStorage or IndexedDB, which the artifact viewer may block. Inline only the icons you use, and don’t embed raw tool output, so the file stays small.
  2. Hand it over and offer to publish. Give the user the file, and offer a private, read-only Atlassian Artifact: nobody else can open it until it’s shared, and people it’s shared with can view it but not edit it. Say what the name and description would be. If they’d rather have a Confluence page, confirm first and create it with createConfluenceContent.

When the user agrees:

  1. Measure it exactly. Byte length: wc -c < file.html. Checksum, as base64 SHA-256, not hex: openssl dgst -sha256 -binary file.html | openssl base64 -A.
  2. Upload. Run createArtifactsUpload (through discover and executeWrite) with length and checksum, then send the exact bytes to the pre-signed URL as its instructions say.
  3. Publish. Run publishArtifact with the contentId from step 4, a name, contentType: text/html, and a description that summarises what the artifact actually contains (up to 1000 characters, used for search). To update an artifact you published earlier, pass its id. Each publish is a new version that can’t be changed.
  4. Share only on request. publishArtifact returns a link that grants nobody access. Offer to share it with the people it’s for (attendees, a leader, a team) and, if the user agrees, call shareArtifact with ari:cloud:identity::user/<accountId> or team ARIs. It only grants view access to named people, never to everyone with the link.

If the client can’t upload over HTTP, hand over the HTML file and say why it wasn’t published.

A static artifact can’t call tools, so it shows what was true when it was built. To keep one fresh, run the skill again and publish with the same id, for example from a scheduled task the user set up to publish. Actions are links, or buttons that copy a command such as /meeting-prep [title].

Live artifact (when the host supports connector access)

A live artifact runs inside a host that explicitly supports tool calls from page code. Having an MCP connection in the agent conversation is not enough. Build one only when the host’s documented runtime and permissions are available, the skill has a “When live” section, and the user requests it or that skill explicitly makes it the default. A skill using answer-first delivery still requires a report or live-export request first.

Read live-artifacts.md before building one, then load only the adapter for the actual host. Use the host’s current documentation when it differs from an included adapter. Do not rename one host’s APIs, capability declarations, connector identifiers or error codes to make them look universal. If the host or its capabilities cannot be confirmed, retain the conversational answer or requested static report and explain why live refresh is unavailable.

A live artifact belongs to its host. Publishing an HTML snapshot to Atlassian Artifacts is a separate, static export, offered only when that service is available and the user requests publication.

Mockups and sample data

When the user asks for a mockup, or gives sample data:

Checklist for skill authors

A skill that loads this file should state: