MCP Server Setup

The MCP server (jd-mcp) exposes AgentGate tools to any MCP-compatible AI client. This is the recommended integration method for most users.

Installation

Option A: npm (simplest)

npm install -g @orbiscend/jd-mcp

Or run without installing:

npx @orbiscend/jd-mcp

Option B: Docker (no Node.js required)

docker pull gustavorbiscend/jd-mcp:latest

Configuration

The MCP server needs your Forge app endpoint URL and an API token. If you haven't generated these yet, see Getting Started.

Variable	Description	Required
JD_ENDPOINT	Forge app endpoint URL (from Jira → Apps → AgentGate for Jira - Tokens)	Yes
JD_TOKEN	API token starting with jfa_	Yes
JD_PROJECT	Default Jira project key (e.g., PROJ)	No
JD_TIMEOUT	Request timeout in milliseconds (default: 30000)	No
JD_MAX_RETRIES	Max retries for rate-limited requests (default: 3)	No

Configuration Priority

Configuration is loaded in this order (first found wins):

1. Environment variables — JD_ENDPOINT, JD_TOKEN, JD_PROJECT
2. Local config — .agentgate-for-jira/config.json in the current directory
3. Global config — ~/.agentgate-for-jira/config.json in your home directory

Shared config with the CLI

If you've already run jd init --global from the CLI, the MCP server picks up that configuration automatically — no additional setup needed.

Client Configuration

Claude Desktop

Edit the config file for your platform:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Using npm:

{
  "mcpServers": {
    "agentgate-for-jira": {
      "command": "jd-mcp",
      "env": {
        "JD_ENDPOINT": "https://your-endpoint-url",
        "JD_TOKEN": "jfa_your_token_here",
        "JD_PROJECT": "PROJ"
      }
    }
  }
}

Using Docker:

{
  "mcpServers": {
    "agentgate-for-jira": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "JD_ENDPOINT",
        "-e", "JD_TOKEN",
        "-e", "JD_PROJECT",
        "gustavorbiscend/jd-mcp:latest"
      ],
      "env": {
        "JD_ENDPOINT": "https://your-endpoint-url",
        "JD_TOKEN": "jfa_your_token_here",
        "JD_PROJECT": "PROJ"
      }
    }
  }
}

Using shared config (if you ran jd init --global):

{
  "mcpServers": {
    "agentgate-for-jira": {
      "command": "jd-mcp"
    }
  }
}

Claude Code

Add to your project settings (.claude/settings.json) or global settings:

{
  "mcpServers": {
    "agentgate-for-jira": {
      "command": "jd-mcp",
      "env": {
        "JD_ENDPOINT": "https://your-endpoint-url",
        "JD_TOKEN": "jfa_your_token_here",
        "JD_PROJECT": "PROJ"
      }
    }
  }
}

Claude Code Plugin

For the best Claude Code experience, also install the AgentGate plugin — it automatically runs prime on session start and provides a /jira skill with built-in documentation.

Cursor

Add to your MCP settings (.cursor/mcp.json in your project or global config):

{
  "mcpServers": {
    "agentgate-for-jira": {
      "command": "jd-mcp",
      "env": {
        "JD_ENDPOINT": "https://your-endpoint-url",
        "JD_TOKEN": "jfa_your_token_here",
        "JD_PROJECT": "PROJ"
      }
    }
  }
}

Windsurf / Other MCP Clients

Most MCP clients follow the same pattern — a command to run the server and env for configuration. Consult your client's documentation for where to add MCP server configuration, then use the same environment variables shown above.

Verify the Connection

After configuring your client, restart it and ask your AI agent:

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

You should see your project's in-progress issues and any pending changes. If something isn't working, check Troubleshooting.

Multi-Project Support

The JD_PROJECT setting is a convenience default. You can override it per tool call by passing a project_key parameter:

prime()                          → uses default project
prime(project_key: "OTHER")      → shows OTHER project status
issues_list(project_key: "ENG")  → searches ENG project

Available Tools

Once connected, your AI agent has access to 15+ tools. See Tools Reference for the full list with parameters and examples.

Quick overview:

Category	Tools
Session	prime
Read	issues_list, issues_show, issues_children, issues_context, issues_transitions, workflow_describe, issues_attachments_download
Write (pending approval)	changes_create, comment, issues_transition, issues_assign, issues_attachments_upload
Manage changes	changes_list, changes_show, changes_update, changes_cancel