Jira Agent Gateway

A public, cloud-agnostic, TypeScript-based MCP-compatible gateway that lets AI agents administer a Jira project through controlled backend tool calls. The default target user is someone who is not a Scrum Master and wants an AI Scrum Master agent to create and manage one Jira project for them. Agents call this gateway; they never receive Jira credentials or call Jira directly.

Architecture

AI agent
  -> MCP tool call or HTTP API request
  -> TypeScript Jira Agent Gateway
  -> Tool registry
  -> Validation layer
  -> Policy and risk engine
  -> Approval hooks, if needed
  -> Jira connector
  -> Jira REST API
  -> Audit logger
  -> Structured response

Gateway capability areas:

• Project administration: create and administer the Jira project owned by the AI Scrum Master workflow through high-risk, approval-gated tools such as create_jira_project.
• Issue operations: search, read, create, update, assign, link, and transition Jira work items.
• Story operations: create Jira stories through create_jira_story.
• Epic operations: create Jira epics through create_jira_epic.
• Bug operations: create Jira bugs through create_jira_bug.
• Assignment defaults: whenever a tool has an assignee option and the caller omits it, the gateway assigns work to the Jira account configured by JIRA_EMAIL.
• Comment operations: add Jira comments through add_jira_comment.
• Sprint operations: create sprints through create_jira_sprint and add work to sprints through add_jira_issues_to_sprint.
• Policy and approval: classify risky writes, require approval where needed, and reject malformed or overly broad requests.
• Audit: log every write action with agent/user identity, payload, approval status, result, and error details.

The same executeTool pipeline is used by MCP and HTTP mode:

1. Validate tool schema with Zod.
2. Validate Jira-specific constraints.
3. Resolve authentication from server-side config.
4. Resolve default assignee from JIRA_EMAIL when an assignee-capable tool does not specify one.
5. Classify risk.
6. Check policy.
7. Request approval for high-risk actions.
8. Execute the Jira API call through the connector.
9. Write an audit event.
10. Return a structured result.

Install

npm install jira-agent-gateway

or run it directly:

npx jira-agent-gateway mcp
npx jira-agent-gateway serve --port 8787

For local development:

npm install
npm run build
node dist/cli/index.js mcp
node dist/cli/index.js serve --port 8787

Configuration

Configuration can come from environment variables or a JSON config file. Environment variables override file values.

JIRA_BASE_URL=https://example.atlassian.net
[email protected]
JIRA_API_TOKEN=replace-me
JIRA_AUTH_MODE=scoped
JIRA_DEFAULT_PROJECT=PROJ
JIRA_APPROVAL_MODE=console
JIRA_AUDIT_LOG_MODE=console

How to get these values:

Variable	How to set it
JIRA_BASE_URL	Use your Jira site URL, usually https://your-company.atlassian.net. Open Jira in your browser and copy the origin before /jira or /browse.
JIRA_EMAIL	Use the email address for the Atlassian account that owns the API token.
JIRA_API_TOKEN	For Jira Cloud, create one at https://id.atlassian.com/manage-profile/security/api-tokens. Copy it once and store it as a secret.
JIRA_AUTH_MODE	Use scoped by default. Use classic only for quick local development, prototyping, or compatibility fallback.
JIRA_DEFAULT_PROJECT	Use the Jira project key shown in issue keys, such as PROJ from PROJ-123.
JIRA_APPROVAL_MODE	Use console for local development, webhook for production approval workflows, or none to deny approval-gated actions.
JIRA_AUDIT_LOG_MODE	Use console for local development, file for local append-only logs, webhook for centralized audit ingestion, or none to disable audit logging.

Jira API Token Recommendation

This framework supports both classic Jira API tokens and scoped Jira API tokens.

TLDR:

• Use a scoped API token for real usage, shared usage, public usage, or production-like usage.
• Use a classic API token only for quick local development, prototyping, or compatibility fallback.

Scoped tokens are recommended because they follow least privilege, limit what the token can access, reduce risk if the token is exposed, and are safer for an AI-agent gateway that may perform real Jira actions. AI agents should never receive the token directly.

Recommended read-only scoped token permissions:

read:jira-work
read:jira-user

Read-only mode supports:

• search_jira_issues
• get_jira_issue
• get_jira_transitions
• reporting
• summarization

Recommended standard write scoped token permissions:

read:jira-work
read:jira-user
write:jira-work
write:comment
write:epic
write:sprint

Standard write mode supports:

• create_jira_issue for Jira stories, epics, tasks, bugs, and other configured issue types
• create_jira_story
• create_jira_epic
• create_jira_bug
• create_jira_sprint
• add_jira_issues_to_sprint
• update_jira_issue
• add_jira_comment
• assign_jira_issue
• transition_jira_issue
• link_jira_issues

Token scopes are only one layer of authorization. The Jira user that owns the token must also have project-level permissions for the target project, especially Browse Projects for read tools and Create Issues for create_jira_issue, create_jira_story, and create_jira_epic.

The default workflow assumes the AI Scrum Master can create and administer the Jira project it owns. That project administration capability is high risk, so it should use admin-scoped permissions plus approval:

read:jira-work
read:jira-user
write:jira-work
write:comment
write:epic
write:sprint
manage:jira-project
manage:jira-configuration

create_jira_project is high-risk and approval-gated by default because it changes Jira administration structure. After the project is created, the agent should administer that one project through gateway policy rather than being given unconstrained Jira access.

Avoid unrelated admin scopes unless the framework intentionally adds that administrative feature. In particular, avoid:

• manage:jira-webhook

This framework is designed for AI-assisted Jira project administration within the project the agent creates or is assigned to manage. It should not administer unrelated Jira projects, global Jira configuration, permissions, workflows, or webhooks unless those capabilities are explicitly added and policy-gated.

Authentication mode examples:

JIRA_AUTH_MODE=scoped

JIRA_AUTH_MODE=classic

The recommended default is:

JIRA_AUTH_MODE=scoped

Security note: Jira credentials must never be exposed to AI agents, prompts, frontend clients, browser code, or public logs. Jira credentials should stay inside the gateway runtime through environment variables, local secrets, or a user-managed secret provider.

AI agents should call structured gateway tools. They should never call Jira directly.

Jira API Token Setup

For Jira Cloud, create the token from your Atlassian account:

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens.
2. Select Create API token for a standard token, or Create API token with scopes if your organization requires scoped tokens.
3. Give the token a purpose-specific name, such as jira-agent-gateway-dev.
4. Choose an expiration date. Atlassian API tokens can expire, so set a reminder to rotate it.
5. Copy the token immediately and store it in a password manager or secret manager. Atlassian does not show the token again.
6. Set JIRA_EMAIL to the Atlassian account email that created the token.
7. Set JIRA_API_TOKEN to the copied token value.

Recommended Jira scopes:

Gateway capability	Scope	Why it is needed
Search issues, read issue details, get transitions	read:jira-work	Allows the gateway to read Jira project and issue data and search issues.
Create and update Jira work items	write:jira-work	Allows the gateway to create, edit, assign, transition, and link Jira issues through controlled tools.
Add comments	write:comment	Allows add_jira_comment to post comments without granting broader admin permissions.
Create and manage epics	write:epic	Allows epic-specific creation and updates when using create_jira_epic or future epic tools.
Sprint work	write:sprint	Allows create_jira_sprint and add_jira_issues_to_sprint to plan work in biweekly or custom sprints.
Create Jira projects	manage:jira-project plus Jira Administrator global permission	Allows create_jira_project to create new Jira projects when project creation mode is enabled.
Configure Jira project defaults	manage:jira-configuration	May be required by Jira Cloud for project creation templates and project configuration defaults.
Resolve or inspect Jira users	read:jira-user	Optional. Useful if you add user lookup, account-id resolution, or richer assignee validation.

Use the smallest scope set that matches the tools you enable. A read-only deployment needs read:jira-work and read:jira-user; the standard AI Scrum Master deployment should include read:jira-work, read:jira-user, write:jira-work, write:comment, write:epic, write:sprint, manage:jira-project, and manage:jira-configuration. Avoid manage:jira-webhook unless you add webhook administration tools.

Important: scoped Atlassian API tokens are designed for the Atlassian API endpoint form https://api.atlassian.com/ex/jira/{cloudId}. The default examples in this README use JIRA_BASE_URL=https://example.atlassian.net, which is the normal Jira site URL for standard API-token basic auth. If you require scoped tokens, configure the connector/base URL strategy accordingly before production use.

Project creation auth note: Jira Cloud project creation is stricter than normal issue work. The Atlassian account that owns the token must have Jira Administrator global permission in the Jira site. A token with only manage:jira-project and manage:jira-configuration may still fail project creation because the workflow also needs to read Jira data and then create epics, stories, comments, sprints, and issues. For the default AI Scrum Master workflow, create the token with the full standard set above from a Jira Administrator account. If Jira still rejects create_jira_project with an authentication error, use JIRA_AUTH_MODE=classic with a classic API token from a Jira site admin account, or move project creation to an OAuth app flow with the same administrative permissions.

Official references:

• Atlassian account API token docs: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
• Jira Cloud scope docs: https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/

For local development, create a .env file from .env.example and replace the placeholder values:

cp .env.example .env

Run with a config file:

jira-agent-gateway mcp --config ./config.example.json
jira-agent-gateway serve --config ./config.example.json --port 8787

Tools

Tool	Risk	Purpose
search_jira_issues	read	Search Jira issues with scoped JQL.
get_jira_issue	read	Read issue details.
create_jira_project	high	Create a Jira project for a Scrum team. Approval-gated by default and requires admin-scoped permissions.
create_jira_issue	low or high	Create Jira work items such as stories, epics, tasks, bugs, and other project-configured issue types. Critical or Blocker priority is high risk.
create_jira_story	low or high	Create a Jira Story in a project. Critical or Blocker priority is high risk.
create_jira_epic	low or high	Create a Jira Epic in a project. Critical or Blocker priority is high risk.
create_jira_bug	low or high	Create a Jira Bug in a project. Critical or Blocker priority is high risk.
update_jira_issue	low or high	Update issue fields. Workflow, security, resolution, fix version, and Critical or Blocker priority changes are high risk.
add_jira_comment	low	Add an issue comment.
assign_jira_issue	low	Assign an issue to a Jira account id. If omitted, the assignee defaults to the account configured by JIRA_EMAIL.
get_jira_transitions	read	List available transitions.
transition_jira_issue	high	Transition an issue. Approval-gated by default.
link_jira_issues	low	Link two issues.
create_jira_sprint	low	Create a Jira sprint on a Scrum board.
add_jira_issues_to_sprint	low	Add stories, tasks, bugs, or other issues to a sprint.

AI Scrum Master Workflow

This gateway is intended to support an AI agent acting as a Scrum Master for users who do not want to administer Jira themselves. The default flow is:

1. Create or select a Jira project with create_jira_project.
2. Create a biweekly sprint with create_jira_sprint.
3. Create epics with create_jira_epic.
4. Create stories with create_jira_story.
5. Create implementation tasks or other work items with create_jira_issue.
6. Create bugs with create_jira_bug.
7. Add the sprint's work items to the sprint with add_jira_issues_to_sprint.
8. Track updates, comments, assignments, links, and transitions through the gateway.

Project creation and project administration are intentionally high-risk and should require human approval. Once approved, the agent should administer the project it created: create biweekly sprints, create epics, add stories, add implementation issues, track bugs, and manage the sprint plan. Sprint and work-item creation are lower risk by default, but still audited.

Creating Projects, Sprints, Stories, Epics, Issues, and Bugs

The gateway is designed to let AI agents create Jira work items through controlled tools.

Use these first-class tools when the intent is specific:

• create_jira_project creates a Jira project.
• create_jira_sprint creates a sprint on a Scrum board.
• create_jira_story creates a Jira Story.
• create_jira_epic creates a Jira Epic.
• create_jira_bug creates a Jira Bug.
• add_jira_issues_to_sprint adds planned work to a sprint.
• create_jira_issue creates any configured Jira issue type by accepting issueType.

Example project:

{
  "key": "SCRUM",
  "name": "My Scrum Space",
  "projectTypeKey": "software",
  "description": "Scrum project managed through the Jira Agent Gateway."
}

Call it through:

create_jira_project(key, name, projectTypeKey, projectTemplateKey, leadAccountId, description)

Example biweekly sprint:

{
  "boardId": 1,
  "name": "Sprint 2026-07-01 to 2026-07-14",
  "startDate": "2026-07-01T09:00:00.000Z",
  "endDate": "2026-07-14T17:00:00.000Z",
  "goal": "Deliver the first validated gateway workflow."
}

Call it through:

create_jira_sprint(boardId, name, startDate, endDate, goal)

The generic create_jira_issue tool passes issueType to Jira, so it can create any issue type configured for the target project, including:

• Story
• Epic
• Task
• Bug
• Custom issue types configured in Jira

Example Story:

{
  "projectKey": "SCRUM",
  "summary": "As a user, I want safer Jira automation",
  "description": "Created through the Jira Agent Gateway with validated inputs and audit logging.",
  "priority": "Medium"
}

Call it through:

create_jira_story(projectKey, summary, description, priority)

If assignee is omitted, the gateway assigns the story to the account configured by JIRA_EMAIL.

Example Epic:

{
  "projectKey": "SCRUM",
  "summary": "AI-assisted Jira operations",
  "description": "Parent initiative for gateway-driven Jira workflows.",
  "priority": "Medium"
}

Call it through:

create_jira_epic(projectKey, summary, description, priority)

Generic issue example:

{
  "projectKey": "SCRUM",
  "issueType": "Bug",
  "summary": "Investigate gateway validation edge case",
  "description": "Created through the generic create_jira_issue tool.",
  "priority": "Medium"
}

Call it through:

create_jira_issue(projectKey, issueType, summary, description, priority)

If assignee is omitted, the gateway assigns the issue to the account configured by JIRA_EMAIL.

Example Bug:

{
  "projectKey": "SCRUM",
  "summary": "Bug: gateway should validate missing sprint id",
  "description": "A bug found during AI Scrum Master workflow testing.",
  "priority": "Medium"
}

Call it through:

create_jira_bug(projectKey, summary, description, priority)

If assignee is omitted, the gateway assigns the bug to the account configured by JIRA_EMAIL.

Add work to sprint:

{
  "sprintId": 42,
  "issueKeys": ["SCRUM-1", "SCRUM-2", "SCRUM-3"]
}

Call it through:

add_jira_issues_to_sprint(sprintId, issueKeys)

Requirements for creation:

• The token must include write:jira-work.
• The default AI Scrum Master workflow token should include read:jira-work, read:jira-user, write:jira-work, write:comment, write:epic, write:sprint, manage:jira-project, and manage:jira-configuration.
• The Atlassian account that owns the token must have Jira Administrator global permission to create projects through the REST API.
• Jira Cloud project creation may require leadAccountId, which is the Atlassian account ID of the project lead. Server/Data Center can use a username string instead.
• Story creation should use create_jira_story; epic creation should use create_jira_epic.
• Epic creation should include write:epic when using scoped tokens.
• Comment creation should include write:comment when using scoped tokens.
• Sprint creation and sprint planning should include write:sprint when using scoped tokens.
• Project creation should include manage:jira-project and may require manage:jira-configuration; some Jira Cloud tenants may require a classic API token from a Jira site admin or an OAuth app flow for this specific operation.
• The Jira user that owns the token must be able to create the same work item manually in Jira.
• The requested issueType must exist in that project and be available on the project's create screen.
• Required Jira fields for that issue type must either be provided by the gateway input or have defaults in Jira.

If Jira returns an error such as "project does not exist or you do not have permission to create issues", the token may be valid but the Jira user likely lacks project-level Create Issues permission or the issue type is not enabled for that project.

HTTP API

curl http://localhost:8787/health
curl http://localhost:8787/tools

Invoke a tool:

curl -X POST http://localhost:8787/tools/search_jira_issues \
  -H 'Content-Type: application/json' \
  -H 'x-agent-id: example-agent' \
  -d '{"jql":"project = PROJ ORDER BY created DESC","maxResults":10}'

Create a Story:

curl -X POST http://localhost:8787/tools/create_jira_story \
  -H 'Content-Type: application/json' \
  -d '{
    "projectKey": "SCRUM",
    "summary": "As a team, we want controlled Jira automation",
    "description": "Created through Jira Agent Gateway",
    "priority": "Medium"
  }'

Create an Epic:

curl -X POST http://localhost:8787/tools/create_jira_epic \
  -H 'Content-Type: application/json' \
  -d '{
    "projectKey": "SCRUM",
    "summary": "AI-assisted Jira operations",
    "description": "Created through Jira Agent Gateway",
    "priority": "Medium"
  }'

MCP Usage

Configure your MCP-compatible AI agent to launch:

{
  "mcpServers": {
    "jira-agent-gateway": {
      "command": "npx",
      "args": ["jira-agent-gateway", "mcp"],
      "env": {
        "JIRA_BASE_URL": "https://example.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "replace-me",
        "JIRA_AUTH_MODE": "scoped"
      }
    }
  }
}

Example agent instruction:

Use the jira-agent-gateway MCP tools to search project PROJ for open bugs.
Do not ask for Jira credentials. If a high-risk write action is required,
request approval through the gateway.

Structured Responses

Success:

{
  "success": true,
  "action": "create_jira_issue",
  "riskLevel": "low",
  "issueKey": "PROJ-123",
  "issueUrl": "https://example.atlassian.net/browse/PROJ-123",
  "summary": "Created Jira issue PROJ-123.",
  "warnings": [],
  "requiresApproval": false,
  "approvalStatus": "not_required"
}

Rejected or approval-gated:

{
  "success": false,
  "action": "transition_jira_issue",
  "riskLevel": "high",
  "errorCode": "APPROVAL_REQUIRED",
  "message": "This action requires human approval before execution.",
  "warnings": [],
  "requiresApproval": true,
  "approvalStatus": "denied",
  "proposedAction": {
    "issueKey": "PROJ-123",
    "transitionId": "31"
  }
}

Approval Providers

The approval layer is pluggable through ApprovalProvider.

Included providers:

• console: prompts a local operator.
• webhook: POSTs approval requests to a URL and expects { "approved": true }.
• none: denies approval-gated actions.

High-risk actions require approval by default.

Audit Loggers

The audit layer is pluggable through AuditLogger.

Included loggers:

• console
• file
• webhook
• none

Every action logs timestamp, agent/user ids when supplied, issue key when available, action, risk level, request payload, approval status, result, and error details.

Security Recommendations

• Never pass Jira credentials in tool inputs.
• Keep Jira credentials in environment variables, local secrets, or your secret manager.
• Do not expose this gateway directly to untrusted clients without authentication and network controls.
• Scope Jira API tokens to the minimum permissions required.
• Keep high-risk actions approval-gated in production.
• Set webhook approval endpoints behind authenticated internal services.
• Store audit logs in append-only or tamper-resistant storage for regulated workflows.
• Prefer narrowly scoped JQL and project-level policies for multi-agent deployments.

Error Handling Strategy

The gateway returns structured errors with stable errorCode values:

• VALIDATION_ERROR: Zod rejected malformed input.
• POLICY_REJECTED: policy denied an action.
• OVERLY_BROAD_QUERY: JQL looked too broad for an agent search.
• APPROVAL_REQUIRED: approval was required and not granted.
• EXECUTION_ERROR: Jira API or connector execution failed.
• UNKNOWN_TOOL: HTTP caller requested an unknown tool.

Testing Strategy

Recommended coverage:

• Unit test every Zod schema with valid and invalid tool payloads.
• Unit test classifyRisk for read, low, and high-risk cases.
• Unit test validateAction for overly broad JQL and high-risk approval gating.
• Mock JiraClient in tool pipeline tests to verify audit and approval behavior.
• Integration test HTTP routes with a fake runtime.
• Smoke test MCP startup with test credentials disabled and mocked connectors.
• Contract test Jira Cloud requests against a mocked Jira REST server.

Connector Model

JiraClient is the adapter boundary. JiraCloudClient implements Jira Cloud REST API v3. JiraDataCenterClient currently inherits the same surface so Data Center-specific REST differences can be added without changing tools or servers.

Project Structure

/src
  /tools
  /connectors
  /policy
  /approval
  /auth
  /audit
  /schemas
  /server
  /cli
  /config