Jiraia MCP

Installable MCP server for Jiraia Agent-First workflows.

Remote-agent install

No monorepo clone is required. Remote Codex agents should install the published npm package at runtime and talk to the Jiraia host through the authenticated Agent HTTP API.

Use @latest after maintainers publish the current package version. To pin a specific audited runtime, replace jiraia-mcp@latest with a concrete version such as [email protected].

Check the published package metadata before wiring a remote agent:

npm view jiraia-mcp version bin

The executable commands are:

npx -y --package jiraia-mcp@latest jiraia-mcp
npx -y --package jiraia-mcp@latest jiraia-mcp-http

Do not pass tokens on the command line. Configure them through environment variables or the Codex MCP server env block so they are not stored in shell history.

Stdio mode with Codex

Add the server to ~/.codex/config.toml:

[mcp_servers.jiraia]
command = "npx"
args = ["-y", "--package", "jiraia-mcp@latest", "jiraia-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.jiraia.env]
JIRAIA_PUBLIC_BASE_URL = "https://jiraia.mixfiscal.com.br"
JIRAIA_AGENT_API_TOKEN = "<agent-token>"
JIRAIA_AGENT_SESSION_ID = "<optional-agent-session-id>"

The canonical stdio install/run command is npx -y --package jiraia-mcp@latest jiraia-mcp: --package jiraia-mcp@latest resolves the npm package, and the final jiraia-mcp selects the stdio executable exposed by that package.

Restart Codex after changing the config.

Minimum stdio environment:

• JIRAIA_PUBLIC_BASE_URL: Jiraia base URL, for example https://jiraia.mixfiscal.com.br.
• JIRAIA_AGENT_API_TOKEN: DB-backed remote-agent HTTP token for /api/agent/** and /api/projects/contract.
• JIRAIA_AGENT_SESSION_ID: optional existing domain agent session id. Set this when resuming an already claimed task.

Write operations sent through this package include deterministic Idempotency-Key headers so retries from stdio or HTTP MCP clients do not drift from the Agent HTTP API contract.

Public MCP surface

The SDK server exposes the 11 canonical Jiraia workflow tools unchanged:

getNextReadyTask
claimTask
loadProjectContract
submitContextBrief
recordEvidence
submitImplementationHandoff
requestReview
approveReview
requestChanges
markBlocked
completeTask

It also exposes the read-only MCP-local diagnostic tool below. It does not have an Agent HTTP sibling route and never prints tokens, Authorization headers, or raw response bodies:

checkJiraiaReadiness(projectId?, agentSessionId?)

Use checkJiraiaReadiness first on a remote setup to validate /api/openapi, AgentBearerAuth, DB-backed token schemas, bearer-token project access, and the optional active-task/session scope before falling back to manual HTTP checks. If projectId is omitted, the tool still validates the public contract but returns a degraded result because project/token scope checks were skipped.

It also exposes startup resources for agents. These resources are read-only MCP context wrappers around existing tools; they do not add HTTP routes or new domain operations.

jiraia://projects/{projectId}/contract
jiraia://projects/{projectId}/active-task-context
jiraia://projects/{projectId}/agent-sessions/{agentSessionId}/active-task-context

Available prompts:

jiraia-execution-checklist
jiraia-review-checklist

Use the project contract resource before implementation, then use the active task context resource to resume the current agent session before pulling or claiming more work.

Environment

• JIRAIA_PUBLIC_BASE_URL: Jiraia base URL. Defaults to http://127.0.0.1:3001.
• JIRAIA_AGENT_API_TOKEN: required DB-backed Jiraia agent token.
• JIRAIA_AGENT_SESSION_ID: optional domain agent session id.
• JIRAIA_AGENT_AUTHORIZED_PROJECT_ID: optional project id used by live smoke checks when JIRAIA_PROJECT_ID is not set.
• JIRAIA_MCP_HTTP_HOST: HTTP MCP bind host. Defaults to 127.0.0.1.
• JIRAIA_MCP_HTTP_PORT: HTTP MCP bind port. Defaults to 3021.
• JIRAIA_MCP_HTTP_PATH: HTTP MCP path. Defaults to /mcp.
• JIRAIA_MCP_HTTP_BEARER_TOKEN: MCP-over-HTTP bearer token. Required when the MCP HTTP server binds to a non-loopback host. This is separate from JIRAIA_AGENT_API_TOKEN.

Smoke validation

From the Jiraia monorepo, run the deterministic local smoke before publishing or changing MCP transport code:

pnpm mcp:smoke:local
pnpm mcp:smoke:package

That command starts a fake Jiraia API plus both MCP SDK and Streamable HTTP clients. It validates tool discovery, loadProjectContract, /health, missing bearer rejection, successful bearer authentication, and token redaction.

pnpm mcp:smoke:package runs npm pack --dry-run --json and validates that the tarball contains README.md, package.json, bundled dist entrypoints, and executable jiraia-mcp / jiraia-mcp-http bins. It does not publish to npm and does not require committing dist.

To validate the same MCP paths against a running Jiraia API, point the smoke at the API host and project. Remote agents should use the Jiraia URL they were given, normally production:

JIRAIA_PUBLIC_BASE_URL=https://jiraia.mixfiscal.com.br \
JIRAIA_AGENT_API_TOKEN=<agent-token> \
JIRAIA_PROJECT_ID=<project-id> \
pnpm mcp:smoke:live

Only Jiraia maintainers with the monorepo and a local web server should replace that URL with http://127.0.0.1:3001. The smoke never prints token values and fails with explicit messages when the API token, project contract, port, path, or MCP HTTP bearer token are wrong.

For a negative bearer-token check, expect a non-zero exit with an explicit JIRAIA_MCP_HTTP_BEARER_TOKEN error:

pnpm --filter jiraia-mcp smoke:local -- --expect-bad-mcp-token

HTTP mode

For MCP Streamable HTTP:

JIRAIA_PUBLIC_BASE_URL=https://jiraia.mixfiscal.com.br \
JIRAIA_AGENT_API_TOKEN=<agent-token> \
JIRAIA_MCP_HTTP_HOST=127.0.0.1 \
JIRAIA_MCP_HTTP_PORT=3021 \
JIRAIA_MCP_HTTP_PATH=/mcp \
npx -y --package jiraia-mcp@latest jiraia-mcp-http

HTTP mode uses the same npm package resolution, but selects the jiraia-mcp-http executable instead of the stdio jiraia-mcp executable.

If JIRAIA_MCP_HTTP_HOST is not loopback, set JIRAIA_MCP_HTTP_BEARER_TOKEN. Clients connecting to that HTTP MCP endpoint must send:

Authorization: Bearer <JIRAIA_MCP_HTTP_BEARER_TOKEN>

When exposing HTTP mode to another machine, keep these token boundaries clear: JIRAIA_AGENT_API_TOKEN authenticates this package to Jiraia's Agent HTTP API; JIRAIA_MCP_HTTP_BEARER_TOKEN authenticates MCP clients to this package's Streamable HTTP server.

MCP Inspector workflow

Use the Inspector as a manual smoke when debugging client compatibility:

npx -y @modelcontextprotocol/inspector npx -y --package jiraia-mcp@latest jiraia-mcp

For Streamable HTTP, start the HTTP executable first, then open the Inspector and connect to http://127.0.0.1:3021/mcp or the configured JIRAIA_MCP_HTTP_PATH. If the endpoint is protected, set the request header:

Authorization: Bearer <JIRAIA_MCP_HTTP_BEARER_TOKEN>

The Inspector should show the 11 workflow tools plus checkJiraiaReadiness. Run checkJiraiaReadiness and at least loadProjectContract before handing the endpoint to an autonomous agent.

Live remote smoke without cloning Jiraia

Remote agents without a monorepo clone can run a live read-only smoke through the npm package by starting either stdio mode in the Inspector or HTTP mode locally, then calling loadProjectContract for the authorized project. Jiraia maintainers with the monorepo can also run:

JIRAIA_PUBLIC_BASE_URL=https://jiraia.mixfiscal.com.br \
JIRAIA_AGENT_API_TOKEN=<agent-token> \
JIRAIA_PROJECT_ID=<project-id> \
pnpm mcp:smoke:live

The live smoke should discover the workflow tools and validate loadProjectContract. For an MCP-first remote readiness check, call checkJiraiaReadiness with the authorized projectId and optional agentSessionId. If write tools fail in a registered MCP client but direct Agent HTTP calls succeed, verify that the installed package version is at least 0.1.3 so the runtime exposes checkJiraiaReadiness, advertises agent-only workflow input schemas, and sends the required Idempotency-Key header for mutating POST calls.