Jira Agent Gateway

A public, cloud-agnostic, TypeScript-based MCP-compatible gateway that lets AI agents interact with Jira through controlled backend tool calls. 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

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. Classify risk.

5. Check policy.

6. Request approval for high-risk actions.

7. Execute the Jira API call through the connector.

8. Write an audit event.

9. Return a structured result.

Related MCP server: MCP Gateway

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
JIRA_EMAIL=you@example.com
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:

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

Standard write mode supports:

• create_jira_issue

• update_jira_issue

• add_jira_comment

• assign_jira_issue

• transition_jira_issue

• link_jira_issues

Avoid admin scopes unless the framework intentionally adds administrative Jira features. In particular, avoid:

• manage:jira-configuration

• manage:jira-project

• manage:jira-webhook

This framework is designed to operate on Jira work items, not administer Jira projects, workflows, webhooks, permissions, or global Jira configuration.

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:

Use the smallest scope set that matches the tools you enable. A read-only deployment needs read:jira-work and read:jira-user; the full default gateway needs read:jira-work, read:jira-user, and write:jira-work. Avoid manage:jira-project, manage:jira-configuration, and manage:jira-webhook unless you add project administration tools, because this gateway does not need global Jira administration permissions.

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.

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

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 an issue:

curl -X POST http://localhost:8787/tools/create_jira_issue \
  -H 'Content-Type: application/json' \
  -d '{
    "projectKey": "PROJ",
    "issueType": "Task",
    "summary": "Investigate agent gateway rollout",
    "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": "you@example.com",
        "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