at-tm-mcp-server

MCP server for the Testament (formerly AssertThat AI Test Manager) 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 at-tm-mcp login, wire it into your AI agent.

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-->  at-tm-mcp-server  --HTTPS-->  Testament Forge app webtrigger
                                      |                              |
                                      | X-User-Access-Token           | assertProjectAccessWithToken()
                                      | X-Cloud-Id                    | -> /rest/api/3/mypermissions
                                      | Authorization: Bearer <shared secret>

The webtrigger side of this already exists in the at-ai-tm repo (src/resolvers/api-tools.js → webTriggerToolsHandler, src/resolvers/auth-remote.js) — it was already built to accept a caller-supplied Atlassian bearer token + cloud ID and check Jira permissions live. This project is the missing piece: it gets that bearer token by having the user log in with Atlassian directly, and keeps it fresh.

Quick start

1. Install

npm install -g @assertthat/at-tm-mcp-server

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

2. Log in

at-tm-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 Jira's Testament admin page. 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. Testament 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 / AT_TM_MCP_CLIENT_ID | Plain text, safe to share within the org. | | Secret | clientSecret / AT_TM_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 at-tm-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. Testament 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 | Under Manage apps, find and click Testament. | | 3 | Testament app page | Open Testament Global Config. | | 4 | Testament Global Config page | Find the MCP connection details section. | | 5 | 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 / AT_TM_MCP_WEBTRIGGER_URL | Specific to this Jira site — a different site (or a dev/staging install of the Forge app) has a different URL. Not tied to an individual user. | | Shared secret | sharedSecret / AT_TM_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 at-tm-mcp login --reconfigure. |

Once all four values are entered, they're saved to ~/.at-tm-mcp/config.json, then your browser opens for the actual Atlassian sign-in, and refresh/access tokens land in ~/.at-tm-mcp/credentials.json. Re-running at-tm-mcp login later skips straight to the Atlassian sign-in step (reusing saved config) — use at-tm-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 AT_TM_MCP_CLIENT_ID, AT_TM_MCP_CLIENT_SECRET, AT_TM_MCP_WEBTRIGGER_URL, AT_TM_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 at-tm-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 at-tm -- at-tm-mcp-server

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

{
    "mcpServers": {
        "at-tm": {
            "command": "at-tm-mcp-server"
        }
    }
}

Other MCP hosts: point them at the command at-tm-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 at-tm 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 at-tm-mcp login from a terminal first.

Everyday commands

at-tm-mcp whoami                who's currently signed in, and to which site
at-tm-mcp status                config + credential file locations, whether everything's configured
at-tm-mcp login --reconfigure   re-enter client ID/secret or webtrigger URL/secret
at-tm-mcp logout                sign out AND wipe all local config (asks to confirm; -y to skip)
at-tm-mcp config get            show current config (secrets masked)
at-tm-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 — same surface as the in-Jira Rovo agent (see manifest.yml's rovo:agent block in at-ai-tm), 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 at-tm-mcp/at-tm-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.