Connect Jira to Codex

Search, read, file, update, and transition issues across your Jira Cloud projects. Add Toolspoke to Codex once and it can use 12 Jira actions. Your Jira credential stays in Toolspoke, and you choose which actions Codex may call.

Set it up in Codex

Three steps, the first one once for every toolkit you will ever add.

  1. Add Toolspoke to Codex

    ~/.codex/config.toml

    [mcp_servers.toolspoke] url = "https://toolspoke.com/mcp"

    Codex signs in to Toolspoke on its own the first time it connects, so there is no key to paste.

  2. Install Jira and connect it

    Add Jira to a project in your Toolspoke workspace.

    Atlassian API token. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.

    Atlassian site name
    Just the subdomain. For https://acme.atlassian.net this is acme.
    Email and API token
    Your Atlassian account email, a colon, then an API token from id.atlassian.com → Security → API tokens. Sent as HTTP Basic. The token inherits your own Jira permissions, so create it on an account that can see the projects this connection should reach.
  3. Choose what Codex may do

    All 12 actions start on. Switch off any of the 5 actions that change something in Jira, and Codex gets a refusal if it tries.

What you can ask Codex for

A few of the Jira actions that only read, so they are safe to try first.

  • Fetch one issue in full, including its description, status, assignee, labels, links and comments
  • List the projects this token can see, with their keys, names, types and leads
  • List the issue types you may actually create in one project
  • Find users by name or email and return their Atlassian accountId

What Codex can do in Jira

7 actions read, 4 write and one deletes or permanently changes something.

Reads

  • Search issues

    Search issues with a JQL query and return a compact summary of each match, key, summary, status, assignee, priority, type, project and dates. This is the entry point for almost every Jira question: get an issue key here, then call get_issue for the full description and get_transitions before moving it. JQL examples: "project = ENG AND status != Done ORDER BY updated DESC", "assignee = currentUser() AND resolution IS EMPTY", "labels = billing AND created >= -14d". The query must be bounded (name a project, an assignee, or a date range) or Jira rejects it. Pagination is by next_page_token, not an offset.

  • Get issue

    Fetch one issue in full, including its description, status, assignee, labels, links and comments. Use it after search_issues when you need the actual body rather than a one-line summary. The description and comment bodies come back as Atlassian Document Format, a JSON tree of paragraphs, not markdown. Call get_transitions if you then want to move the issue.

  • Get transitions

    List the workflow transitions available on one issue right now, with the transition id and the status each one leads to. Always call this before transition_issue: transition ids are per-workflow and per-issue-state, so the id that closed one issue will not close another. Costs nothing and changes nothing.

  • List projects

    List the projects this token can see, with their keys, names, types and leads. Call this first when you need a project_key for create_issue or a JQL query and do not already have one. Filter with query to match a name or key substring.

  • List issue types

    List the issue types you may actually create in one project. Task, Bug, Story, Sub-task, and whatever else that project's scheme defines. Call this before create_issue: issue type names are per-project, and a name that works in one project is rejected in another. Takes the project key from list_projects.

  • List users

    Find users by name or email and return their Atlassian accountId. A search string is required. Jira has no unfiltered listing here. This is the only way to get the accountId that create_issue and update_issue need for an assignee; Jira rejects usernames and email addresses in those fields. Email addresses may be hidden depending on each user's privacy settings.

  • Get current user

    Return the account this connection authenticates as: display name, email, accountId, time zone and locale. Use it to confirm which Jira account an agent is acting as, and to get the accountId for JQL such as assignee = currentUser(). Takes no arguments and changes nothing, which is why it is the install-time health check.

Writes

  • Create issue

    File a new issue. Needs a project key, a summary and an issue type name, call list_projects for the key and list_issue_types for the type names that project actually offers, because a type valid in one project is often invalid in another. The description is plain text; it is wrapped into Atlassian Document Format for you, so do not pass ADF JSON. Returns the new issue's id, key and self URL.

  • Update issue

    Change fields on an existing issue: retitle it, rewrite the description, reassign it, reprioritise it, relabel it or set a due date. Pass only the fields you want changed; anything you omit is left alone. This cannot move an issue between workflow statuses, that is transition_issue. Jira answers with an empty body on success.

  • Add comment

    Post a comment on an issue. Prefer this over update_issue when you are reporting progress or asking a question, rewriting the description destroys what was there, a comment does not. The body is plain text and is wrapped into Atlassian Document Format for you. Comments are visible to everyone who can see the issue.

  • Add worklog

    Log time against an issue. time_spent uses Jira's own duration syntax, "3h", "1d 2h", "45m". Omit started and Jira stamps it now; supply it to backdate an entry. Adding a worklog adjusts the issue's remaining estimate automatically. Returns the created worklog entry.

Deletes or permanently changes

  • Transition issue

    Move an issue to another workflow status, resolve it, close it, send it back to the backlog. Call get_transitions first for the transition_id, because ids differ per project workflow and per current status. Classified destructive rather than write: a workflow may offer no route back from the status you land in, transitions fire notifications and automation rules, and some post-functions are not reversible. An optional comment is posted with the transition.

Jira in Codex: questions

Does Codex see my Jira credential?

No. The credential is stored encrypted in Toolspoke, and the gateway adds it to each call. Codex only ever talks to Toolspoke, and the dashboard shows the last four characters of the credential and nothing more.

Can I stop Codex from changing things in Jira?

Yes. Each of the 12 actions can be switched off for a project. Turn off the 5 that change something and Codex can only read.

Will 12 actions crowd Codex's context?

No. Toolspoke shows Codex five bridge tools, plus a guide where a toolkit has one, and Codex searches for the Jira action it needs when it needs it. Adding more toolkits does not add more tools to its list.

Does the same work in ChatGPT?

ChatGPT and Codex share one OpenAI account. In ChatGPT, add a custom MCP connector in its settings and paste the same address.

What does it cost?

Tool calls are free on every plan, and a Jira call does not run in a sandbox, so it bills nothing.

Try Jira in Codex

Free to start, and tool calls cost nothing on any plan.