Skip to main content

Getting Started

This guide walks you through setting up AgentGate from scratch. By the end, you'll have an AI agent that can read your Jira issues and propose changes through a human-approved workflow.

Time required: ~10 minutes.

Prerequisites​

  • A Jira Cloud instance (Jira Software or Jira Service Management)
  • Admin access to install the Forge app (or ask your Jira admin)
  • Node.js 18+ (for CLI or npm-based MCP server) or Docker (for containerized MCP server)

Step 1: Install the Forge App​

The Forge app is the backend that powers everything — it handles Jira API calls, manages the approval queue, and provides the Review UI.

  1. Go to the AgentGate Marketplace listing
  2. Click Get it now and select your Jira site
  3. The app installs in seconds — it runs natively within Atlassian's infrastructure
Forge-native

The Forge app runs entirely inside Atlassian's infrastructure — no external servers, no third-party databases. Jira data is exposed to your AI agent only through authenticated, scoped API tokens under your control.

Step 2: Generate an API Token​

Both the CLI and MCP server authenticate using API tokens generated inside Jira.

  1. In Jira, go to Apps → AgentGate for Jira - Tokens
  2. Copy the Endpoint URL displayed at the top of the page — you'll need this for configuration
  3. Click Generate Token and give it a descriptive label (e.g., "Claude Desktop", "CI Pipeline")
  4. Copy the token immediately — it's shown only once and starts with jfa_

Each token is tied to a Jira user account, so actions proposed through that token are attributed to that user. You can generate multiple tokens for different agents or team members.

Copy your token immediately

The token is only displayed once when generated. If you lose it, you'll need to generate a new one.

Step 3: Choose Your Integration Method​

Pick the method that matches how your AI agent works:

MethodBest forInstall command
MCP ServerClaude Desktop, Claude Code, Cursor, Windsurf, any MCP clientnpm install -g @orbiscend/jd-mcp or Docker
CLITerminal-based agents, Claude Code, scripting, CI/CDnpm install -g @orbiscend/jd-cli
Claude Code PluginClaude Code users who want auto-context and /jira skillclaude plugin add github:Orbiscend/agentgate-claude-plugin

Most users should start with the MCP Server — it's the most flexible option and works with any MCP-compatible AI client. See the detailed setup guides linked above.

Step 4: Configure Your Connection​

Whichever method you chose, you need to provide three things:

SettingEnvironment VariableDescription
Endpoint URLJD_ENDPOINTThe URL from the Tokens page (Step 2)
API TokenJD_TOKENYour jfa_ token (Step 2)
Default ProjectJD_PROJECTYour Jira project key, e.g., PROJ (optional)

Quick setup with the CLI:

npm install -g @orbiscend/jd-cli
jd init --global

The jd init command walks you through entering your endpoint, token, and default project. It saves the config to ~/.agentgate-for-jira/config.json, which the MCP server also reads automatically.

Or set environment variables in your MCP client configuration — see MCP Setup for client-specific instructions.

Step 5: Verify Your Connection​

With the CLI:

jd status    # Shows connection status and your user name
jd prime     # Shows your project overview

With the MCP Server: Ask your AI agent:

"Run the prime tool and show me the project status."

If successful, you'll see your project's in-progress issues and any pending changes.

Step 6: Try It Out​

Ask your AI agent to read something:

"Show me the open issues in my project."

The agent calls issues_list and shows your backlog. Now try a write operation:

"Add a comment to PROJ-123 saying 'Testing AgentGate setup.'"

The agent proposes a comment. Open Jira and go to Apps → AI Changes Review to see the pending change. Click Approve and the comment appears on the issue.

That's it — you're up and running. The agent reads from the projects you've scoped, proposes changes, and you approve them.

Next Steps​