Pagination broken: searchJiraIssuesUsingJql never returns nextPageToken or pagination metadata

[atk-flywheel]

Pagination broken: searchJiraIssuesUsingJql never returns nextPageToken or pagination metadata

Summary

The searchJiraIssuesUsingJql tool never returns pagination fields (nextPageToken, nextCursor, isLast) in its response,
making it impossible to paginate beyond the first page of results.
The totalCount field in the response reflects the number of results on the current page (equal to maxResults),
not the total number of matching issues, which makes it unusable for detecting whether more pages exist.

Environment

• MCP endpoint: https://mcp.atlassian.com/v1/mcp
• Tool: searchJiraIssuesUsingJql
• Client: Claude Code (claude-code CLI)
• Date observed: March 20, 2026
• Jira Cloud instance: Confirmed on at least one production Jira Cloud tenant

Expected behavior (per MCP pagination spec)

Per the MCP Pagination specification,
servers should return a nextCursor field (or in the Atlassian MCP's case, nextPageToken) when more results exist.
Clients treat a missing cursor as the end of results.

The tool's input schema accepts a nextPageToken parameter,
and the skills documentation in this repo
instructs agents to "use nextPageToken from results" for pagination.
This confirms pagination was designed to work.

Actual behavior

The response envelope only contains three keys:

{
  "issues": {
    "totalCount": 20,
    "nodes": [ ... ],
    "webUrl": "https://..."
  }
}

• No nextPageToken, nextCursor, or isLast field is returned, regardless of whether more results exist.

• totalCount equals maxResults (or the number of nodes if fewer results exist), not the true total matching the JQL query.

• Attempting to pass a value for the nextPageToken input parameter returns an error:

  {"errorMessages": ["The provided next page token is invalid or expired."], "errors": {}}

Reproduction steps

1. Connect to the Atlassian MCP server

2. Call searchJiraIssuesUsingJql with a JQL query that matches more results than maxResults:

   {
     "cloudId": "<your-cloud-id>",
     "jql": "project = <PROJECT> AND fixVersion = \"<version>\"",
     "fields": ["key", "summary"],
     "maxResults": 5
   }

3. Observe the response:

   • totalCount equals 5 (matches maxResults, not the true total)
   • No nextPageToken or isLast field is present
   • Only nodes, totalCount, and webUrl keys exist

4. Repeat with maxResults: 20 and maxResults: 100 on the same query:

   • totalCount changes to 20 and 100 respectively, always matching maxResults
   • No pagination metadata is ever returned

5. Try passing nextPageToken: "5" or any value:

   • Returns error: "The provided next page token is invalid or expired."

Impact

• Any JQL query returning more results than maxResults (max 100) silently drops results with no indication that more exist.
• Agents following the documented pagination pattern (nextPageToken from results) will always see a missing token and conclude pagination is complete after the first page.
• There is no workaround within the MCP tool itself. The only mitigation is to use JQL ORDER BY key ASC with AND key > "LAST-KEY" to manually paginate, but this is fragile and undocumented.

Likely root cause

This issue aligns with widely reported pagination problems in Atlassian's newer
/rest/api/3/search/jql endpoint, which replaced the deprecated /rest/api/2/search endpoint.
The newer endpoint has known issues with nextPageToken handling:

• Tokens that return the first page in an infinite loop
• Tokens returned as "expired" immediately
• isLast never returning true
• Pagination fields missing entirely from responses

The MCP server appears to be using this newer endpoint but not receiving
(or not forwarding) the pagination fields from the underlying API response.

Community references

These Atlassian Community threads document the same underlying API pagination issues:

• JIRA Search pagination with nextPageToken doesn't update on 2nd page
• REST: The new /rest/api/3/search/jql endpoint is a complete disaster
• JRACLOUD-94632: The nextPageToken parameter not works on the initial request
• Jira Cloud REST API v3 /search/jql: Slower Fetching with nextPageToken & No totalIssues
• Pagination issue after migrating to new JQL Search endpoint

Suggested fix

1. Return nextPageToken (or nextCursor per the MCP spec) in the response when more results exist.
2. Return the true totalCount of matching issues, not the count of the current page.
3. If the underlying Jira API is not providing reliable pagination tokens, consider falling back to the deprecated /rest/api/2/search endpoint which uses offset-based pagination (startAt + total) reliably, or implement server-side cursor management.

[P-Weezy]

+1 on this. We're building a weekly reporting automation that pulls bug metrics from Jira via MCP, and this pagination/totalCount issue makes it impossible to get accurate counts for any query returning >100 results.

Our use case: We run ~10 JQL queries to gather cumulative and weekly bug metrics (total open bugs, bugs linked to Intercom, user-facing bugs, new bugs created, duplicates, etc.). Most of these queries return well over 100 results. Since totalCount is capped at maxResults and there's no working pagination, we can't get accurate counts for 6 out of 10 metrics and have to fall back to manual dashboard checks.

Specific impact:

• maxResults: 1 with a query matching 1,649 issues → totalCount: 1
• maxResults: 100 with the same query → totalCount: 100
• No way to distinguish 101 results from 1,649

If totalCount returned the true total (as the Jira REST API does), we wouldn't even need pagination — just the count. That alone would unblock our automation entirely.

[THuffWT]

is there any movement here? This issue is causing a lot of problems for our company trying to pull ticket data through the MCP with claude code.

[puneet-atlassian]

Thanks for the detailed report - this should now be fixed.

searchJiraIssuesUsingJql structured content now includes cursor pagination metadata via pageInfo. The structured content shape is now:

{
  "issues": {
    "nodes": [
      { "...": "issue fields" }
    ],
    "webUrl": "https://<site>.atlassian.net/issues?jql=<encoded-jql>",
    "pageInfo": {
      "hasNextPage": true,
      "endCursor": "<nextPageToken>"
    }
  }
}

Clients can pass pageInfo.endCursor back as the nextPageToken input on the next searchJiraIssuesUsingJql request, and use pageInfo.hasNextPage to determine whether more results are available.

We have also removed the misleading totalCount value from this structured content path. That value previously represented the number of issues returned in the current page, not the true number of matching Jira issues and was misleading.

Returning a true total count is a separate concern. This could be added to the existing search tool response in the future, but we’d treat that as a separate feature rather than part of this pagination fix.

[THuffWT]

@puneet-atlassian this still isn't working. Claude Code stalls on the last page. Is this not merged and live yet? If not, do you have an ETA when? Our team has a CC skill that needs this to work, it stalls everytime on the last page.

[puneet-atlassian]

@THuffWT Could you clarify what you mean by the last page is stalled?
Do you mean the same page is returned repeatedly, the client keeps requesting after the last page, or the final response still contains a non-null cursor?

For the last page, the structured content should include something like this

{
  "issues": {
    "pageInfo": {
      "hasNextPage": false,
      "endCursor": null
    }
  }
}

If possible could you share a redacted example of the tool response you’re seeing, especially structuredContent.issues.pageInfo?

[iosamaatlassian]

Hey @THuffWT
I will close the issue but please feel free to reopen it, if it's still not working for you.