Skip to content

Using Alces

Alces connects an AI agent (like Claude) to your organization's Jira Data Center instance. Once it's set up, you talk to the agent in plain English — "what's the status of PROJ-123?", "file an IT request for a broken laptop," "who's on the Developers permission scheme?" — and the agent picks the right underlying operation for you. You never need to know a tool name, write JSON, or touch Jira's REST API directly.

This guide is for that day-to-day use. If you're setting up or deploying Alces itself, see the main README instead.

Before you start

Data Center only. Alces does not support Jira Cloud (*.atlassian.net). If your Jira URL ends in atlassian.net, this tool won't work — Data Center or Server only.

You'll need:

  • A Jira Data Center instance that your organization has already stood up.
  • A Personal Access Token (PAT) for your Jira account — ask your Jira administrator how your organization issues these if you don't already have one (Jira: Profile → Personal Access Tokens).
  • Someone to configure Alces with that PAT as JIRA_USER_TOKEN, connected to your AI agent client (e.g. Claude Desktop). This is a one-time setup step — see the main README for the connection details.

Some tools — 169 of the 557, marked [ADMIN] in each page's tool tables (or Yes in the Admin? column on the Admin page) — additionally need a second, separate JIRA_ADMIN_TOKEN PAT configured by whoever runs your Alces deployment. If that token isn't configured, admin tools simply don't exist as far as the agent is concerned — it has no way to even attempt them, so there's nothing to accidentally reach for.

Upgrading from 1.0.2

If you're moving from an earlier Alces install that ran on JIRA_USER_TOKEN alone, four things changed in this release. Three can look like regressions — none of them are — and one moves in your favour. Here's what happened and what to do:

  • 78 more tools now require JIRA_ADMIN_TOKEN and no longer show up in the tool list. This release checked every tool's admin requirement against a real Jira Data Center instance instead of assumption. The tools that moved fall into four groups: 33 instance-wide configuration and directory reads (roles and role actors, screens, issue type schemes, custom fields, priority schemes, application roles, application properties and advanced settings, email templates, group membership, duplicate-user and user-anonymization lookups, the Assets index status, and JSM queue settings and request-type permissions); the 8 monitoring/JMX status and toggle tools; 28 hard deletes, removals and archive/restore operations (Assets object, object-type, status-type and attachment deletes, JSM organization deletes and organization/participant removals, project and issue-type-scheme deletes, issue and project archive/restore, role deletes and role-actor removals); and 9 role, project-category, JSM queue-setting and customer-creation writes. None of these ever actually worked for a non-admin account — Jira itself always refused them; this release just stops advertising a tool your account can't use, instead of letting you hit a confusing permission error after the fact. See CHANGELOG.md in the main repo for the complete per-tool list. To get one of these back: ask whoever runs your deployment to configure JIRA_ADMIN_TOKEN, or, if token escalation is enabled for that tool's domain (see "Note on token escalation" below), ask the agent to retry the call with the admin credential.
  • 29 tools stopped requiring JIRA_ADMIN_TOKEN and now work on your user token alone. The same audit found these succeed for a plain licensed user, so they no longer vanish when JIRA_ADMIN_TOKEN is unset: the 10 permission-, notification- and workflow-scheme lookups (including admin_update_permission_scheme); 6 instance and reindex status reads (admin_server_info, admin_get_reindex_info, admin_get_reindex_progress, admin_get_reindex_requests_bulk, get_configuration, validate_license); your own 4 personal column and property settings; the 4 screen-tab editing tools; custom-field create and delete; the two user/group pickers; and jsm_get_request_type_groups. Nothing to do — they simply appear in the tool list now where they didn't before.
  • 19 tools that widen access now require confirm: true. Creating a user account or a JSM customer, granting a licensed seat, sharing a filter, adding someone to a group or a service desk organization, adding a grant to a permission scheme, and assigning a permission scheme all now need your explicit go-ahead before they run, the same way deleting something already did — the refusal names exactly what's being granted. Fourteen of the 19 came from one access-widening sweep; add_user_to_group, admin_create_permission_scheme_grant and update_application_property were gated a little earlier in the same release cycle, and create_user and jsm_create_customer were added last, once a pre-release audit found that a new Jira account takes a licensed seat from the instance's default application access even when the call names no applications — and that creating a JSM customer, which likewise mints an account that can log in, had been left ungated only to stay consistent with create_user. update_user gained the same gate conditionally — only when the call grants a licensed application seat or reactivates a disabled account; a plain edit still needs no confirmation. See Troubleshooting for what these refusals look like, or CHANGELOG.md for the full tool list.
  • Three tools now check required fields before calling Jira. transition_issue, update_issue, and jsm_create_request look up the relevant screen or request-type fields first and refuse up front if something required is missing, instead of sending an incomplete request and leaving Jira half-finished. If you relied on the old single-call behavior, pass skipFieldValidation: true to skip the check and go straight to Jira exactly as before.

Installing Alces in Claude Desktop

If nobody's set this up for you yet, you can do it yourself — no command line, no editing config files:

  1. Go to the project's GitLab Releases page and download the latest alces-mcp-<version>.mcpb file.
  2. In Claude Desktop, open Settings → Extensions, then Advanced settings → Extension Developer → Install Extension…, and select the file you just downloaded.
  3. When prompted, enter your Jira URL and PAT(s) (see "Before you start" above for how to get a PAT) — Claude Desktop handles storing these for you.

That's it — the agent now has access to everything below.

Other ways to install Alces

If you (or whoever sets Alces up for your team) uses one of these tools instead of Claude Desktop's manual extension install above, Alces is also available through:

  • Smithery (a directory/installer for AI tools): npx @smithery/cli@latest mcp add moosejudge/alces-mcp --client claude — or browse the listing at smithery.ai/servers/moosejudge/alces-mcp.
  • Claude Code (Anthropic's command-line coding agent): add the moosejudge catalog once with claude plugin marketplace add https://gitlab.com/moosejudge/mcp-marketplace.git, then install with claude plugin install alces-mcp@mcp-marketplace.
  • Codex CLI (OpenAI's command-line coding agent): codex plugin marketplace add https://gitlab.com/moosejudge/alces-mcp.git, then codex plugin add alces-mcp@alces-mcp.
  • The official MCP Registry: Alces is listed there under com.moosejudge/alces-mcp, with a real npm package reference (alces-mcp) — any MCP-Registry-aware client can resolve and install it directly from there.
  • npm directly: Alces is published as alces-mcp — any MCP client that lets you configure a raw command/args can run it with npx -y alces-mcp, no install or download step at all. See the main README for per-client config examples.

Whichever way you install it, once it's connected you have access to everything below the same way.

Your first request

Once you're connected, just ask for something in plain language:

"What's the status of PROJ-456?"

The agent looks up the issue and shows you its status, summary, and assignee. From there you can keep going conversationally — "move it to Done," "who's it assigned to," "add a comment saying the fix is deployed." You don't need to structure your request any particular way; describe what you want and the agent works out which tool(s) to call.

What you can do

Alces covers a lot of ground — 557 tools in total. You won't need most of them most of the time, but here's what's available, grouped by what you're actually trying to do:

Page What it covers
Core Issues & Search Finding, creating, and updating issues; JQL search; reference data like statuses and priorities. Start here for day-to-day issue work.
Attachments, Links, Watchers & Worklogs Everything else a single issue can carry: files, links to other issues, watchers, votes, time tracking, subtasks.
Agile: Boards, Sprints & Epics Scrum/Kanban boards, sprints, epics, and backlog management (requires Jira Software to be enabled on your instance).
Projects, Dashboards, Versions & Components Project setup and lifecycle, versions, components, dashboards, roles, categories.
Filters, Personal Settings & Sessions Saved searches, your own account details, active sessions.
Users, Groups & Permissions Looking people up (mostly no admin needed), plus user/group/permission-scheme management (mostly admin).
JSM Service Desk Customer requests, service desks, organizations, queues, approvals, SLAs — Jira Service Management.
JSM Assets Your organization's CMDB — servers, laptops, licenses, and whatever else is tracked as an "object."
Admin & Instance Configuration Cluster health, reindexing, workflow schemes, screens, and instance-wide configuration. Admin-heavy, biggest page — most people won't need this one.

Not sure where something lives? Just ask the agent in plain language — it has access to all of these, and this page split is here to help you read the docs, not to constrain what you can ask for.

Note on tool visibility: to keep sessions lightweight, Alces only advertises the Core Issues & Search tools to the agent by default — everything else on this page activates on request (the agent can do this itself by calling activate_tool_domain, or you can ask it to "turn on the admin/agile/JSM/etc. tools"). Every tool is still reachable by name even before its group is activated — this only affects what shows up when the agent lists its available tools. If you're setting Alces up yourself and want everything visible from the start, see the ALCES_TOOL_GROUPS environment variable in the main README.

Note on token escalation: most tools can retry a call with the elevated admin credential (useAdminToken: true) when your own permissions are the actual obstacle — but only for tool domains the person who set up Alces has explicitly opted in via ALCES_TOKEN_ESCALATION_DOMAINS (unset by default, so this is off unless someone turned it on). If you hit a permission error, it's worth asking the agent to retry with the admin credential — it'll tell you if that's not enabled for this deployment. When escalation does fire, the response says so, and the wording tells you why: "(performed with the elevated credential — the calling account lacked permission for this specific action)" means your own token was tried first and Jira refused it, while "(performed with the elevated credential because useAdminToken:true was requested — the calling account's own permissions were never tried)" means the call went straight to the admin credential, so it says nothing about whether you could have done it yourself. Either way, that's how you know the admin token was actually used. A fixed set of 41 tools can never escalate, no matter what — asking for it on one of those (or on an admin-only tool, or on the server's own meta-tools) is refused with an error saying why that particular tool can never use the admin credential, rather than quietly running without it.

Anything you do to a work item that Jira records under your name, including voting and watching: create_issue, bulk_create_issues, update_issue, update_epic, update_issue_estimation, transition_issue, assign_issue, add_comment, update_issue_comment, pin_issue_comment, add_worklog, update_worklog, add_issue_attachments, add_vote, remove_vote, add_watcher, delete_watcher, the JSM equivalents (jsm_create_request, jsm_add_comment, jsm_add_request_attachment, jsm_attach_temporary_file, jsm_answer_approval, jsm_perform_customer_transition) and the Assets ones (assets_add_comment, assets_add_attachments).

Anything scoped to your own account or session: get_myself, update_myself, update_myself_password, get_my_permissions, get_my_preference, set_my_preference, delete_my_preference, list_favourite_filters, get_default_share_scope, set_default_share_scope, get_project_type_accessible, jsm_list_my_requests, create_session, get_current_session, delete_current_session and invalidate_websudo.

Substituting the admin identity there would either corrupt Jira's audit trail of who did what, or not mean anything for an action that's inherently "as you" — an escalated get_my_permissions, for instance, would report the admin account's permissions as if they were yours. Asking the agent to retry one of these with the admin token has no effect: it isn't offered the option at all, so the call quietly runs on your own token with no error and no disclosure — if one of these is refusing you, the admin token genuinely can't help; the tool itself needs a different argument or a different account. See Token escalation in the main README for details.

If something goes wrong

See Troubleshooting for common errors and what they mean.

Going deeper

Every page above is curated — realistic example prompts and a capability table, not a full API reference. For the exhaustive technical detail behind every tool (every field, every parameter), see docs/api-catalog.md.