Check and troubleshoot MCP

Check the connection

A listed server proves that the client loaded its configuration. A successful tool call also checks the credential and your access to the requested content.

Inspect the atlassian server in your client's MCP settings.
Check for jira_search, jira_get_issue, confluence_search, and confluence_get_page.
Ask the client to run this Jira search with a limit of one result:

Use jira_search with JQL "assignee = currentUser() ORDER BY updated DESC",
limit 1, and fields "summary,status". Do not update anything.

Ask the client to search a Confluence space you can access. Replace YOUR_SPACE_KEY:

Use confluence_search with query "type = page AND space = YOUR_SPACE_KEY"
and limit 1. Then use confluence_get_page to read the returned page.
Do not update anything.

A Jira search with no matches can still succeed. A Confluence search with no matches does not prove that page access works; try a known page URL.

Common errors

Symptom	Check
`uvx` not found or process cannot start	Run `command -v uvx` on macOS or `(Get-Command uvx).Source` in PowerShell. Put that absolute path in the client configuration.
Works in a terminal, fails in the desktop app	Use absolute executable and environment-file paths. Fully restart the app after changes.
Environment file not found	Check the path and filename. On Windows, make sure the editor did not add `.txt`.
Invalid JSON or TOML	Merge into the existing parent object or table. Use doubled backslashes in Windows JSON; use literal strings in Windows TOML.
Jira HTTP 401	Check `JIRA_PERSONAL_TOKEN`, its expiry, and the `its-pro.ucsd.edu` URL. An Atlassian Cloud API token is not a Jira Data Center PAT.
Confluence HTTP 401	Check the account email, token expiry, and whether the token has scopes. The token and URL format must match.
HTTP 403 or inaccessible content	Check that the same account can open the issue, project, space, or page in a browser. Token scopes can further restrict access.
Only Jira or only Confluence tools appear	Check that the missing service has its required credentials and that its tools appear in `ENABLED_TOOLS`.
Write tools are missing	The initial setup intentionally exposes four read-only tools. Follow Allow selected write tools if you need updates.
Startup timeout	Run `uvx mcp-atlassian==0.23.0 --help` in a terminal to complete the initial package download. Then restart the MCP connection.
OpenCode rejects the server definition	Match the configuration to OpenCode 1.x or 2.x. Their parent keys and enable/disable fields differ.

If TLS verification fails, check the computer's trusted certificates and network access. Keep certificate verification enabled. The pinned server uses the operating system trust store by default; see MCP Atlassian authentication.

Scoped Confluence tokens

Atlassian requires scoped tokens to use api.atlassian.com, not the direct ucsdcollab.atlassian.net site URL. The API base has this form:

https://api.atlassian.com/ex/confluence/YOUR_CLOUD_ID/wiki

The token must also cover every API operation used by the selected tools. Changing the URL alone does not grant those scopes. See Atlassian's scoped-token guide.

The setup guide uses the documented non-scoped token configuration. A complete scoped-token recipe for both search and page reads has not been verified for this pinned server version.

Update an older configuration

Use the same pinned server version for Jira and Confluence.
Keep the Jira PAT and Confluence API token in separate fields.
Use the current ENABLED_TOOLS names from this guide instead of copying an old toolset list.
Use local stdio transport. The IGNORE_HEADER_AUTH and ALLOW_GLOBAL_CRED_FALLBACK settings concern HTTP authentication; this setup does not need them.
After the new connection works, remove or disable duplicate old Jira and Confluence server entries.

Do not turn off token expiration to solve an authentication error. Replace an expired token and restart the connection.

Verification record

On September 4, 2026, mcp-atlassian==0.23.0 passed local MCP initialization, registration of the four documented tools, and an authenticated Jira search on macOS. Confluence tool registration used synthetic credentials; no authenticated Confluence request was made. The client formats and Windows instructions were checked against current documentation, not tested on every platform.

If the connection still fails, contact tritonai@ucsd.edu. Include the client version, operating system, server version, and sanitized error. Omit tokens and private issue or page content.