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 (marked "admin" throughout this guide) 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.

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 — 556 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 (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.

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.