AssertThat ATM MCP Server

MCP server for the AssertThat - Autonomous Test Management for Jira (AssertThat ATM) Forge app. Instead of pasting an app-generated token, each user signs in with their own Atlassian account (OAuth 2.0 / 3LO). From then on:

• Every tool call carries that user's own Atlassian access token, so Jira's own permission model decides what they can touch — a user with access to projects A/B/C who tries to act on project E is rejected by Jira itself, not by anything this server invents.
• Access + refresh tokens are cached locally, so the user doesn't have to log in again next session (refresh tokens are used to silently renew the access token).
• This is a global CLI + a stdio MCP server: install once, run assertthat-atm-mcp login, wire it into your AI agent.

The package installs two commands:

| Command | What it is | | --------------------------- | ------------------------------------------------------------------------------- | | assertthat-atm-mcp | The CLI you run in a terminal: login, logout, whoami, status, config. | | assertthat-atm-mcp-server | The stdio MCP server your AI agent launches. You don't run it by hand. |

Cloud-only. Jira Data Center/Server has no equivalent OAuth 3LO / accessible-resources / mypermissions APIs, so this design doesn't extend to it.

How it fits together

Claude / MCP host  --stdio-->  assertthat-atm-mcp-server  --HTTPS-->  AssertThat ATM webtrigger
                                         |                                    |
                                         | X-User-Access-Token                | checks the user's Jira
                                         | X-Cloud-Id                         | permissions for the project
                                         | Authorization: Bearer <shared secret>

The AssertThat ATM app accepts a caller-supplied Atlassian access token + cloud ID and checks that user's Jira permissions live on every call. This server is the client side of that: it gets the access token by having the user log in with Atlassian directly, and keeps it fresh.

Quick start

1. Install

npm install -g @assertthat/atm-mcp-server

Not published to npm yet? From a clone of this repo: npm install && npm run build && npm link — same result, assertthat-atm-mcp and assertthat-atm-mcp-server land on your PATH either way.

2. Log in

assertthat-atm-mcp login

The first run interactively asks for four values before it opens your browser to sign in with Atlassian. Two come from an Atlassian Developer Console OAuth app, two come from the AssertThat ATM admin page in Jira. Both are one-time, per-organization/per-site setup — most teammates just ask whoever did it first for the values instead of repeating these steps.

2a. Atlassian OAuth 2.0 (3LO) app → clientId + clientSecret

One person per organization needs to register this app once; everyone else reuses the same Client ID/Secret pair.

| Step | Where | What to do | | ---- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | https://developer.atlassian.com/console/myapps/ | Click Create → OAuth 2.0 integration. Give it a name (e.g. AssertThat ATM MCP) and accept the terms. | | 2 | Left sidebar → Authorization tab | Find the OAuth 2.0 (3LO) row and click Configure. In the Callback URL field, enter http://localhost:8765/callback, then Save changes. | | 3 | Left sidebar → Permissions tab | Click Add on both User identity API and Jira API to attach them to the app. | | 4 | Same Permissions tab, per API just added | Click Configure on User identity API → check the scopes for read:me. Click Configure on Jira API → check the scopes for read:jira-user and read:jira-work. Save. | | 5 | Left sidebar → Settings tab | Scroll to the Authentication details section. Copy the Client ID directly. Click Copy (or reveal, then copy) next to Secret. |

| Value | Maps to | Notes | | ------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Client ID | clientId / ASSERTTHAT_ATM_MCP_CLIENT_ID | Plain text, safe to share within the org. | | Secret | clientSecret / ASSERTTHAT_ATM_MCP_CLIENT_SECRET | Treat like a password — only visible once unless you rotate it. | | Callback URL | (not stored — must just match) | Only needs to change if you customize redirectPort via assertthat-atm-mcp config set redirectPort <port>; keep the port in this URL and in that config in sync. | | Scopes | read:me read:jira-user read:jira-work | This is the CLI's built-in default — you don't need to pass it yourself unless your app grants a different scope string. |

2b. AssertThat ATM webtrigger → webtriggerUrl + sharedSecret

Self-service, no Forge CLI needed — but you do need Jira admin rights on the site you're connecting to.

| Step | Where | What to do | | ---- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------- | | 1 | Jira → ⚙️ Settings (top right) | Click Apps. | | 2 | Apps sidebar | Click AssertThat ATM to open the app's admin page. | | 3 | AssertThat ATM admin page | Find the MCP connection details section. | | 4 | MCP connection details | Click Copy next to the webtrigger URL. Click Reveal, then Copy, next to the shared secret. |

| Value | Maps to | Notes | | -------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Webtrigger URL | webtriggerUrl / ASSERTTHAT_ATM_MCP_WEBTRIGGER_URL | Specific to this Jira site — a different site (or a dev/staging install of the app) has a different URL. Not tied to an individual user. | | Shared secret | sharedSecret / ASSERTTHAT_ATM_MCP_SHARED_SECRET | Shared by every teammate connecting to this site. If it leaks, click Regenerate secret on the same page, then have everyone re-run assertthat-atm-mcp login --reconfigure. |

Once all four values are entered, they're saved to ~/.assertthat-atm-mcp/config.json, then your browser opens for the actual Atlassian sign-in, and refresh/access tokens land in ~/.assertthat-atm-mcp/credentials.json. Re-running assertthat-atm-mcp login later skips straight to the Atlassian sign-in step (reusing saved config) — use assertthat-atm-mcp login --reconfigure to re-enter the four values instead (e.g. after rotating the shared secret, or to switch organizations/sites).

Prefer environment variables instead (e.g. for CI, or to avoid writing secrets to disk)? Set ASSERTTHAT_ATM_MCP_CLIENT_ID, ASSERTTHAT_ATM_MCP_CLIENT_SECRET, ASSERTTHAT_ATM_MCP_WEBTRIGGER_URL, ASSERTTHAT_ATM_MCP_SHARED_SECRET — env vars always take priority over the config file, and skip the setup prompt entirely once all four are set.

Access tokens refresh automatically and transparently on every tool call once they're close to expiry — you won't need to log in again unless Atlassian revokes the refresh token (long inactivity, or you revoking this app's access from your Atlassian account settings). Run assertthat-atm-mcp login again any time to switch accounts or sites.

3. Add it to your AI agent

login prints these once it finishes, but for reference:

Claude Code:

claude mcp add assertthat-atm -- assertthat-atm-mcp-server

Claude Desktop — add to claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
    "mcpServers": {
        "assertthat-atm": {
            "command": "assertthat-atm-mcp-server"
        }
    }
}

Other MCP hosts: point them at the command assertthat-atm-mcp-server with no arguments — no path or env block needed, since config/credentials already live on disk from step 2.

Restart Claude Desktop (or reload the MCP connection in Claude Code), then confirm the assertthat-atm server shows as connected and its tools (jira_issue, test_cases, etc.) are available.

The server process itself only serves tool calls — it doesn't run the interactive login flow (a stdio MCP process can't prompt for browser interaction the way a CLI invocation can). Always run assertthat-atm-mcp login from a terminal first.

Everyday commands

assertthat-atm-mcp whoami                     who's currently signed in, and to which site
assertthat-atm-mcp status                     config + credential file locations, whether everything's configured
assertthat-atm-mcp login --reconfigure        re-enter client ID/secret or webtrigger URL/secret
assertthat-atm-mcp logout                     sign out AND wipe all local config (asks to confirm; -y to skip)
assertthat-atm-mcp config get                 show current config (secrets masked)
assertthat-atm-mcp config set <key> <value>   set one config value manually

Tools exposed

jira_issue, jira_subtasks, folders, test_cases, test_cases_bulk, test_plans, executions, analytics, tags, issue_links — the same tools as the AssertThat ATM Rovo agent inside Jira, reachable here over the webtrigger instead.

Development

Running from a local clone instead of the global install:

npm install
npm run build   # compiles src/ -> dist/
npm run dev     # tsc --watch, recompiles on save
node dist/cli.js login   # or: npm run login

npm link (after building) puts assertthat-atm-mcp/assertthat-atm-mcp-server on your PATH pointing at this clone's dist/, so the Quick start commands above work identically against your working copy.

After changing src/, rebuild (npm run build) and restart the server in your MCP host to pick up the change — Claude doesn't hot-reload a running stdio server.