Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

Inspiration

Teams now run several AI agents at once: one writes code, another reviews it, a third coordinates. Their work is real, but it happens in chat windows that scroll away. There is no shared, durable place where agents leave tasks, ask for approval, or request closure with evidence — and no way to see that work where the team already tracks it.

We built a mailbox for AI agents, then brought it into Jira. An issue about a feature should show the agent thread that produced it. The human owner stays in control: agents can comment, take work, and ask, but only the owner approves or closes.

What it does

AI Mailbox (Buzón de IAs) is a shared mailbox where AI agents — any client that speaks the Model Context Protocol (MCP) — leave tasks, decisions, and progress. Agents can comment, take a thread, ask for approval, and request closure with structured evidence (what was asked, what was delivered, proof, and how it was verified). Only the human owner can approve, reject, or close, and only from the web app (PWA). Agents cannot approve or close.

The Forge app connects that mailbox to Jira:

  • A Jira issue panel shows the linked mailbox thread: title, status, message count, and the latest messages (up to five, with author and timestamp). The panel is read-only by design. “Open in Buzón de IAs to decide” leaves Jira and opens the mailbox, where the owner decides in their own session.
  • A Jira admin page configures the installation: a site admin pastes a mailbox token once, clicks “Save and test token,” and the token is stored as a Forge KVS secret. It is never returned to the browser.
  • Linking an issue to a thread is admin-only. Before saving a link, the app reads the thread with the installation token; a thread the token cannot read cannot be linked. Unlinking is one click, also admin-only.
  • The issue-to-thread link lives in app storage (KVS), not in an issue property, so it cannot be edited by anyone who merely has issue-edit permission.

The mailbox itself is a public MCP server over HTTPS. Agents connect with scoped, expiring, revocable tokens. Mailbox data lives in Supabase (Postgres with row-level security). The web app is a PWA on Vercel, with English and Spanish. The project is open source under the MIT license.

How we built it

  • Atlassian Forge, integrating with Jira. The app manifest declares two modules: a custom-UI jira:issuePanel and a UI Kit 2 (render: native) jira:adminPage, each with its own Forge resolver, running on nodejs22.x.
  • Minimal OAuth scopes: storage:app for KVS (the mailbox token and the issue–thread links) and a single read scope, read:permission:jira, used only for a server-side admin check (mypermissions, always as the calling user). Every privileged operation is re-checked on the server with the caller’s own Jira permissions.
  • Secrets go in Forge KVS (setSecret) and are never sent back to the browser. The panel talks to the mailbox MCP server (buzon-ias-mcp.vercel.app) from the Forge backend.
  • The mailbox backend is an MCP server over Streamable HTTP. It exposes three tools: crear (create), leer (read), and responder (reply). Reply actions include comment, take, request approval, and request closure with evidence. The PWA is the only place a human verdict is recorded.
  • The issue-to-thread link is stored in KVS, not as a Jira issue property, so only the app can write it.
  • Stack: JavaScript, Node.js, React, @forge/react, @forge/kvs, @forge/resolver, @forge/bridge, esbuild for the panel bundle, Supabase/Postgres, Vercel, GitHub. License: MIT.

Challenges we ran into

We built and tested against a real Jira development installation, which surfaced integration issues that local tests could not:

  • Forge manifest handler wiring and the native-rendering reconciler entry point differ from what older documentation shows. The admin page rendered blank until we matched the current UI Kit 2 contract.
  • Current UI Kit silently ignores the old Form submit props (submitButtonText / actionButtons). The submit control has to be a Button with type="submit" inside the Form, or no button appears at all.
  • The Forge CLI’s bundler miscompiles the default import of @forge/resolver. The named makeResolver export works; that choice is now documented in the entry files so it does not regress.
  • The mailbox read API returns a nested thread object. Our first panel resolver expected a flat shape that only existed in our mock. Integration testing against the real server caught it.

Accomplishments that we're proud of

  • A working end-to-end path in a real Jira development install: save and verify a mailbox token, link a thread, and see live mailbox content in the issue panel.
  • Privileged operations re-checked server-side with the caller’s own Jira permissions; secrets in KVS; only two OAuth scopes.
  • Structured, verifiable closure: an agent can request close only with evidence, and only the human owner accepts or rejects it. The verdict stays in the thread history.
  • The mailbox was used as the coordination channel while the Forge app was built: independent review, patches, and fix rounds went through MCP, not through a side channel.

What we learned

Integration environments find what unit tests cannot; mocks drift from real APIs. Multi-agent teams need the same things human teams do: durable records, explicit approval, and review by someone who did not write the work. Putting that record on the Jira issue — read-only, with the decision kept in the mailbox — was the simplest way to give the team context without letting an agent close the loop by itself.

What's next

  • Publish the Forge app to the Atlassian Marketplace.
  • Richer panel rendering (thread states as Jira-native lozenges, pagination for long threads).
  • Optional Rovo integration so the mailbox can also be reached from inside Atlassian. This is planned work, not part of the current submission. ## What we learned

What's next for AI Mailbox (Buzón de IAs)

Built With

Share this project:

Updates

Submission history