FogBugz MCP Server
A Model Context Protocol (MCP) server that lets Codex interact with FogBugz over the official XML API. The server exposes curated tools for searching, auditing, and updating cases so agents can stay inside Codex while FogBugz handles the workflow.
🧭 Overview
The server runs over the MCP stdio transport via @modelcontextprotocol/sdk. Every tool call is framed, schema-validated, and logged, so you can reason about FogBugz state while keeping your MCP client stable. The project ships with:
Canonical tool names (
search_cases,case_events,view_case, etc.) mapped to FogBugz XML commands.A markdown help resource (
help) that Codex can read when it needs a refresher.Structured logging of outbound FogBugz traffic to simplify debugging.
⚙️ Setup
Prerequisites
Node.js 20.x or newer (ESM + undici are required).
npm (ships with Node) and
git.A FogBugz account with access to the projects you plan to touch.
Codex configured to load MCP servers from
~/.config/codex/config.toml.
1. Clone & install
Use any workspace path you like; the examples below assume ~/dev/fogbugz-mcp.
2. Pick the values you will embed in the MCP config
Codex can pass environment variables directly to the MCP process via the env = { ... } block you define in config.toml, so you don’t need to export them in your shell. Decide on the following values (but keep them out of git/notes):
Variable | Required | Description |
| ✅ | Full FogBugz API endpoint, e.g.
. |
| ✅ | Personal API token with permission to read/update the target projects. |
| optional | File path for JSON logs (e.g.
). |
| optional | Set to
for verbose request/response logging. |
Because these values end up in config.toml, keep that file outside version control (Codex stores it under your home directory by default). If you sync dotfiles, mask or template the token first.
3. Generate a FogBugz token (once per user)
Sign in to FogBugz in a browser.
Click your avatar ➜ User Options (or Profile depending on your skin).
Open API Tokens and click Create API Token.
Give the token a descriptive label (e.g., “Codex MCP”) and copy the generated value.
Store it securely (password manager, OS keychain) and set
FOGBUGZ_TOKENin your environment.
Why the fuss? FogBugz tokens grant the same rights as your account—treat them like passwords, rotate them when someone leaves the team, and never paste them into support tickets or commit history.
4. Wire the server into Codex
Edit ~/.config/codex/config.toml (create the file if it does not exist) and add:
Keep the
argspath in sync with wherever you cloned the repo.Codex injects these env vars when it launches the server, so there is no need to export them globally; treat this block like a private secrets store.
If Codex reports a handshake timeout, raise
startup_timeout_secslightly to give Node more time to boot.env property must have no line breaks.
5. Smoke test the transport
You can sanity-check the MCP handshake without Codex:
You should see a newline-framed JSON response containing the tool registry. Confirm help, search_cases, and case_events show up.
🔎 FogBugz query syntax primer
Most tools rely on FogBugz’ search syntax. Highlights:
ixBug:207291finds a single case by ID.assignedto:"Tier 2" status:activefilters by owner and status (use quotes for spaces).project:"NexPort Solutions" opened:"this week"mixes project filters with date shortcuts.parent:207291orchildren:207291retrieves hierarchy relationships.Use
cols=to request additional XML columns (comma separated). The MCP server auto-adds safe defaults for each tool. For the full grammar, see FogBugz’ “Search Syntax” guide or runfogbugz.helpfrom Codex for quick reminders.
🧰 MCP tool catalog
Tool | Purpose | Key arguments & notes |
| Returns the markdown help/recipes that ships with the server. | No arguments. Useful when Codex needs onboarding text. |
| Run arbitrary FogBugz searches. |
(required) plus optional
. Used for lightweight listings. |
| Same as
but forces the
column so you get the full event log (can be very large). | Ideal when auditing conversations or history. |
| Fetch one case by ID with optional columns; auto-includes
. | Arguments:
, optional
. Returns a normalized JSON payload plus raw XML. |
| Create a new FogBugz case. Supports parent/milestone/category and the custom
field. | Required:
,
. Optional:
,
,
,
,
,
,
. |
| Update an existing case. You can change the title,
, or any FogBugz XML field via the
map. | Required:
. Optional:
,
,
,
. |
| Add a comment/event to a case. |
,
. |
| Upload an attachment using base64 content. |
,
,
. |
| Return the parent case plus its children (ID, title, assignee, timestamps). |
(parent). Handles null IDs by coercing response columns. |
| Resolve a case with optional closing comment or field edits. |
, optional
,
. |
| Re-open a case with optional comment/field payload. | Same schema as
. |
| Enumerate every FogBugz category and metadata (
, workflow flags, etc.). | No arguments; handy for validating the
you pass to
. |
Example MCP call payload:
🧪 Workflow snippets
Search then inspect: Call
search_caseswithq="ixBug:207291", grab the ID, then callview_casefor enriched columns.Full audit trail: Use
case_eventswithcols="sTitle,events"to stream every change along with event codes (see FogBugz docs for the code legend).Create + comment: After
create_casereturns the newixBug, immediately calladd_commentto capture additional context while Codex still has it in memory.Hierarchy review:
list_childrenreturns both the parent echo and each child’sixBug,sTitle,sStatus,ixPersonAssignedTo, anddtLastUpdated.
🩺 Troubleshooting
Symptom | Likely cause | Fix |
returns zero tools | Env vars missing or startup failed before registration. | Check
and ensure
/
are exported before Codex launches. |
or
when calling a tool | MCP framing mismatch caused by a crash or malformed FogBugz response. | Inspect the log file for the failing tool; run it manually with
and re-try with
. |
Continuous heartbeat but Codex times out | The server never received
because Codex could not read from stdio. | Confirm stdin/stdout aren’t redirected and that no other process is binding to the same command. |
error | Tool names contained dots/aliases. | Stick with the canonical names listed above; aliases were removed. |
Attachments or
truncated | Large payloads can hit FogBugz or Codex limits. | Narrow your
filter, request fewer columns, or avoid event-heavy cases unless needed. |
🔒 Security notes
Tokens inherit your FogBugz permissions. Store them in env vars or OS keychains—not in git, Codex transcripts, or screenshots.
Rotate tokens periodically and immediately after leaving a shared machine.
Log files can capture request URLs (including tokens if you misconfigure the base URL). Keep them on trusted disks and redact before sharing.
If you must share logs, strip case content to avoid leaking customer data.
📜 License
MIT (or internal use). Update if distributing publicly.
👤 Maintainer
Daniel Pupek — Chief Systems & Software Architect, Advanced Systems Technology, Inc.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables interaction with FogBugz issue tracking system through its XML API, allowing users to search, create, update, and manage cases, comments, and attachments directly from their MCP client.