atlassian-proxy

An MCP proxy in front of the Atlassian cloud MCP server (https://mcp.atlassian.com/v1/mcp) with OAuth authentication, built on FastMCP. A middleware layer between the client and Atlassian trims the verbose JSON responses of Jira/Confluence — issue searches, epics, and other heavy payloads shrink by 70–90%, directly reducing token consumption on every tool call.

NixOS-native: everything is provisioned by a Nix flake via python3.withPackages — no venv/pip and no broken manylinux wheels (the main reason the upstream server does not work on NixOS: jq links against the system libjq here).

Motivation

Atlassian MCP responses are bloated with irrelevant fields. For example, the status of a single issue in search results arrives as:

{
  "status": {
    "self": "https://api.atlassian.com/ex/jira/.../status/10009",
    "description": "",
    "iconUrl": "https://<host>.atlassian.net/images/icons/statuses/generic.png",
    "name": "On Hold",
    "id": "10009",
    "statusCategory": {
      "self": "https://api.atlassian.com/ex/jira/.../statuscategory/2",
      "id": 2, "key": "new", "colorName": "blue-gray", "name": "To Do"
    }
  }
}

After the proxy, all that remains is {"status":{"name":"On Hold"}} — everything the model needs, nothing it doesn't.

Quick start (NixOS / Nix)

nix run                         # start the proxy on http://127.0.0.1:8080/mcp
# with options:
nix run . -- --port 9000 --log-level DEBUG

With direnv: run direnv allow in the directory — the dev shell activates automatically, then python proxy.py.

Quick start (pip)

On any other system, install the dependencies from requirements.txt and run the script directly:

python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
python proxy.py                 # http://127.0.0.1:8080/mcp

Requires Python 3.11+. The jq package ships prebuilt manylinux wheels, so no system libjq is needed outside of NixOS.

Tokens live only in process memory: on the first tool call of a session, the proxy opens a browser for the OAuth login. Tokens are never written to disk — each session logs in once, independently. Only the tool manifest is cached, so the tool list is available to the client before login.

Options

Flag	Default	Description
--transport	http	stdio | http | sse | streamable-http
--host	127.0.0.1	bind address for http/sse (0.0.0.0 to expose externally)
--port	8080	port for http/sse
--upstream	https://mcp.atlassian.com/v1/mcp	upstream Atlassian MCP server
--config	slim_config.yaml next to the script	slimming configuration
--manifest	~/.cache/atlassian-proxy/tool_manifest.json	cached upstream tool manifest
--name	atlassian-proxy	proxy server name
--log-level	INFO	logging level

Connecting to Claude Code

Add the server to the project's .mcp.json (or the user-level config). Two modes are supported:

stdio — the client launches the proxy as a subprocess (nothing needs to be kept running manually):

{
  "mcpServers": {
    "atlassian": {
      "command": "nix",
      "args": ["run", "/path/to/atlassian-proxy", "--", "--transport", "stdio"]
    }
  }
}

http — the proxy runs as a separate process (nix run) and the client connects by URL; convenient to keep running in another terminal. If you already have an Atlassian MCP entry, just change type to http and set the url:

{
  "mcpServers": {
    "atlassian": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Each Claude Code session starts its own proxy process and performs the OAuth browser login on the first tool call; the token lives until the process exits.

Response slimming (slim_config.yaml)

ResponseSlimMiddleware compiles a jq program from the configuration and runs the text responses of the listed tools through it (all other tools pass through untouched).

Field	Description
tools	names of MCP tools the slimming applies to
remove	field names removed at any depth (self, avatarUrls, …)
compress	field → which subfields to keep when the value is an object (assignee: [displayName])
remove_nulls	drop null/empty customfield_* entries
log	log the savings per request (tool, sizes, percentage saved)

Adjust it to your needs: add tools to tools, fields to remove/compress.

Architecture

• proxy.py — the FastMCP proxy plus the slimming middleware; argparse CLI.
• slim_config.yaml — slimming configuration.
• flake.nix — devShells.default (Python for development), packages.default (the runnable atlassian-proxy), apps.default (for nix run).

Dependencies

On Nix, all dependencies come from nixpkgs (see flake.nix): fastmcp, mcp, jq, pyyaml, authlib, httpx, uvicorn. Outside of Nix, install the same set from PyPI via requirements.txt.