Skip to content
jtk

Security

Credential Storage

Section titled “Credential Storage”

File-based credentials

Section titled “File-based credentials”

When you run jtk auth, credentials are saved to:

~/.config/jtk/credentials.json
  • File permissions are set to 0600 (owner read/write only)
  • The file contains your Jira domain, email, and API token
  • Tokens are stored in plaintext — protect this file as you would any secret

Environment variables

Section titled “Environment variables”

For CI/CD or ephemeral environments:

Terminal window
export JIRA_DOMAIN="mycompany"
export JIRA_EMAIL="me@example.com"
export JIRA_API_TOKEN="ATATT3x..."

Environment variables take priority over stored credentials.

Two-Layer Safety Model

Section titled “Two-Layer Safety Model”

jtk provides defense-in-depth for AI agent access through two independent security layers.

Layer 1: Token Scopes

Section titled “Layer 1: Token Scopes”

jtk uses Atlassian’s granular API token scopes. Create a Jira app token at id.atlassian.com and select only the scopes you need.

Run jtk auth to see the full recommended scope list, or refer to the Configuration guide.

Read-only (18 scopes): Issues, comments, attachments, worklogs, projects, versions, boards, sprints, dev-status, users, JQL, and permission introspection.

Full access (add 7 write scopes): Create/update/delete issues, comments, worklogs, issue links, attachments, and sprints.

If a scope is missing, the Jira API returns 403 — the operation is blocked at the API level before jtk even processes the response.

Layer 2: Permission Introspection

Section titled “Layer 2: Permission Introspection”

On startup, the MCP server checks your Jira account’s project-level permissions via:

GET /rest/api/3/mypermissions

Write actions are only included in tool descriptions if the account has the corresponding Jira permission (CREATE_ISSUES, DELETE_ISSUES, TRANSITION_ISSUES, etc.). This prevents:

  • AI agents attempting operations that would fail
  • Wasted API calls and tokens
  • Confusing error messages

Principle of Least Privilege

Section titled “Principle of Least Privilege”

For MCP server usage, combine both layers:

  1. Token scopes — select only the granular scopes you need (read-only is safest)
  2. Jira permissions — use a dedicated account with limited project roles if needed
  3. Tool disabling — explicitly deny tools via JIRA_DISABLED_TOOLS

Data Flow

Section titled “Data Flow”
AI Agent ←→ jtk (local) ←→ Jira Cloud API (HTTPS)
  • All data stays on your machine (or wherever jtk runs)
  • jtk communicates with Jira Cloud over HTTPS only
  • No telemetry, analytics, or third-party data sharing
  • MCP stdio transport is local-only (no network exposure)
  • HTTP Streamable transport (--port) binds to localhost by default

Rate Limiting

Section titled “Rate Limiting”

jtk includes built-in rate limiting to:

  • Prevent overwhelming the Jira Cloud API
  • Avoid 429 (Too Many Requests) responses
  • Protect against runaway AI agent loops

Tool Disabling

Section titled “Tool Disabling”

Reduce attack surface by disabling unnecessary tools:

Terminal window
export JIRA_DISABLED_TOOLS="manage_attachments,manage_worklogs"

This completely removes the tools from the MCP server — they won’t appear in tool listings or be callable.