atlassian-proxy

Local stdio MCP proxy that sits in front of Atlassian's hosted Rovo MCP server (https://mcp.atlassian.com/v1/mcp) and trims it down for Claude Code.

Claude Code (stdio) -> index.js -> mcp-remote (subprocess, OAuth) -> https://mcp.atlassian.com/v1/mcp

What it does:

• Exposes only the tools listed in ALLOWED_TOOLS in index.js (the ones jira-ops/jira-reviewer actually use) — everything else upstream is hidden from tools/list.

• Auto-injects cloudId, contentFormat, responseContentFormat into every call and strips those params from the schema Claude sees, so Claude never has to know about them.

• Recursively strips noisy keys (avatarUrls, self, iconUrl, _links, expand, browseUrl, ...) from every tool result before returning it.

Requirements

• Node.js (any version supporting native ESM / type: "module").

• npx available on PATH (used to spawn mcp-remote).

Related MCP server: JIRA MCP Server

Install

First check whether Node.js is already installed — if it is, and node_modules is already present in this folder, npm install is not needed:

node -v

If that fails (Node not found), install Node.js first, then:

cd C:\Users\Dz\oktanetest\atlassian-proxy
npm install

This installs @modelcontextprotocol/sdk and mcp-remote from package.json.

Run standalone (manual smoke test)

node index.js

It speaks MCP over stdio, so running it directly just blocks waiting for a client on stdin. On the first call to any Jira/Confluence tool it spawns npx -y mcp-remote https://mcp.atlassian.com/v1/mcp as a child process, which opens a browser window for Atlassian OAuth login. Once authorized, mcp-remote caches the token, so subsequent runs don't need to re-authenticate. [atlassian-proxy] ready on stderr means it connected to upstream and is serving the filtered tool list.

Register with Claude Code

Register this proxy under the name atlassian-proxy, not atlassian — that keeps it from colliding with the real hosted Atlassian/Rovo MCP server if that one is also registered under atlassian.

Add it as a stdio MCP server for the project, e.g. in that project's Claude Code config (mcpServers block):

{
  "atlassian-proxy": {
    "type": "stdio",
    "command": "node",
    "args": ["<path-to-atlassian-proxy>\\index.js"],
    "env": {}
  }
}

If the real atlassian MCP server is also registered, disable it (don't remove it) so only this proxy's filtered tools are active: run /mcp in Claude Code, select the atlassian server, and choose the disable option. Re-enable it there later if you ever need the full, unfiltered upstream tool set back.

Restart/reconnect Claude Code (or the MCP connection) after registering so it picks up the new server. Tools from this proxy will appear under the atlassian-proxy prefix (e.g. mcp__atlassian-proxy__getJiraIssue), already limited to ALLOWED_TOOLS and stripped of cloudId/ contentFormat/responseContentFormat.

Token savings stats

Since Claude Code runs this proxy hidden and its stderr isn't visible in chat, savings are written to files instead:

• logs/token-savings.log — JSONL, one line per tools/list/tools/call event (tokensSavedIn, tokensSavedOut, running totals).

• logs/stats-summary.txt — overwritten after every event with the current running totals.

Two numbers are tracked (both are estimates — char-count / 4, not a real tokenizer, since no Claude tokenizer is wired in):

• Kept out of Claude's context (tokensSavedIn): tool-list trimming (ALLOWED_TOOLS) plus noise stripped from tool results (stripNoise).

• Claude didn't have to generate (tokensSavedOut): the constant params (cloudId, contentFormat, responseContentFormat) the proxy injects on Claude's behalf.

To watch it live, open a separate terminal and tail the summary file:

Get-Content logs\stats-summary.txt -Wait

Troubleshooting

• Hangs with no ready message: npx -y mcp-remote ... is likely waiting on the OAuth browser flow — check for a browser window/prompt.

• Tool not available in Claude: confirm the tool name is in ALLOWED_TOOLS in index.js; anything not listed is filtered out of tools/list and rejected on tools/call.

Stale/expired auth (401 Unauthorized, or could not resolve cloudId from getAccessibleAtlassianResources)

Claude Code's /mcp reconnect only restarts the node index.js stdio process — it does not force re-auth. The actual OAuth token lives one layer down, cached on disk by the mcp-remote child process at ~/.mcp-auth/mcp-remote-<version>/<server-hash>_tokens.json, keyed by the upstream server URL. If that token is stale (expired, revoked, or was already stale before the node process even restarted), every tool call fails with 401/could not resolve cloudId regardless of how many times you reconnect in Claude Code, because reconnecting never touches that cache.

Full recipe, in order:

1. Clear the cache: rm -rf ~/.mcp-auth (Windows: C:\Users\<you>\.mcp-auth). This wipes the cached client registration, PKCE verifier, and token for every mcp-remote-backed server on the machine — safe, it's pure OAuth-client state, nothing else depends on it.

2. Re-authenticate standalone, outside Claude Code, in its own terminal:

   cd C:\Users\Dz\oktanetest\atlassian-proxy
   npx -y mcp-remote https://mcp.atlassian.com/v1/mcp --host 127.0.0.1

   Let this run in the foreground (or a background shell you can watch) and complete the browser login at your own pace. Do not try to re-authenticate by reconnecting atlassian-proxy inside Claude Code first — Claude Code's own connection-setup timeout races the interactive OAuth flow, since index.js's main() doesn't open its own stdio side until the entire upstream mcp-remote connect (including you clicking through the browser) resolves. If Claude Code gives up first, it kills index.js and its mcp-remote child mid-handshake — the browser may still show "Authorization successful!", but the token exchange gets cut off before tokens.json is written (you're left with only client_info.json/code_verifier.txt in ~/.mcp-auth, no token — check for that if this happens). Running mcp-remote standalone first removes that race entirely; once it prints Proxy established successfully (exit code 0), the token is safely cached.

3. Only then reconnect atlassian-proxy in Claude Code (/mcp). It spawns the same mcp-remote, finds the now-valid cached token, and connects immediately with no browser step.

--host 127.0.0.1 in index.js's spawn args (not upstream mcp-remote default) is required on Windows: mcp-remote's local OAuth callback server binds 127.0.0.1 only, but its default redirect_uri hostname is localhost. On a Windows machine where localhost resolves to ::1 first (check with Resolve-DnsName localhost), the browser's post-login redirect hits an address nothing is listening on — the callback page shows "Unable to connect" and the auth code is stranded. Do not remove this flag.

EADDRINUSE on the callback port (e.g. listen EADDRINUSE: 127.0.0.1:3736) after a previous auth attempt was interrupted: npx on Windows doesn't always kill the full child process tree when its parent is cancelled, so a previous mcp-remote can be left orphaned, still holding the port. Find and kill it before retrying:

Get-NetTCPConnection -LocalPort <port> | Select-Object OwningProcess
Stop-Process -Id <pid> -Force