I ran into a couple of architectural and packaging issues while trying to connect the jules-mcp-server (v0.2.0) to Claude Code using npx. Claude Code ultimately helped diagnose and patch the issues locally to get it working, but I wanted to report them here so they can be fixed upstream!
Here is a breakdown of the three issues encountered:
- Missing shebang in the published binary
The published dist/server.js file ships without a shebang (#!/usr/bin/env node). Because of this, trying to run the server via npx jules-mcp-server immediately fails with a Syntax error: "(" unexpected error.
Fix/Workaround: Locally, I had to patch the file by injecting the shebang on line 1, or bypass npx entirely by running /usr/bin/node explicitly against the server.js file.
- Single shared StreamableHTTPServerTransport instance (HTTP 500 error)
The server currently constructs a single StreamableHTTPServerTransport instance at startup and attempts to reuse it for every request. Because the MCP SDK's stateless transport is designed to be single-use, after the initial connection, every subsequent initialize request returns an HTTP 500 error. Each time an MCP client polls or connects, it burns the one-shot transport, leaving the session broken.
Fix/Workaround: I had to patch dist/server.js locally to construct a fresh McpServer and StreamableHTTPServerTransport per request, adhering to the MCP SDK's stateless pattern.
- Documentation/Configuration Clarity
Many MCP clients (like Claude Code) default to stdio when adding a server via npx. Because this server specifically uses an Express HTTP listener and the streamable-http transport on 127.0.0.1:3323, standard CLI install commands will cause the client to hang waiting for JSON-RPC frames over stdio.
Suggestion: It would be helpful to add a warning in the README that standard stdio MCP configurations will not work, and explicitly document setting it up as a background service/daemon with the "type": "http" configuration.
My current local workaround:
For anyone else stuck on this, I bypassed npx entirely by installing it globally, patching dist/server.js to fix the transport instance issue, and running it as a background systemd user service mapped as an http MCP resource.
I ran into a couple of architectural and packaging issues while trying to connect the jules-mcp-server (v0.2.0) to Claude Code using npx. Claude Code ultimately helped diagnose and patch the issues locally to get it working, but I wanted to report them here so they can be fixed upstream!
Here is a breakdown of the three issues encountered:
The published dist/server.js file ships without a shebang (#!/usr/bin/env node). Because of this, trying to run the server via npx jules-mcp-server immediately fails with a Syntax error: "(" unexpected error.
Fix/Workaround: Locally, I had to patch the file by injecting the shebang on line 1, or bypass npx entirely by running /usr/bin/node explicitly against the server.js file.
The server currently constructs a single StreamableHTTPServerTransport instance at startup and attempts to reuse it for every request. Because the MCP SDK's stateless transport is designed to be single-use, after the initial connection, every subsequent initialize request returns an HTTP 500 error. Each time an MCP client polls or connects, it burns the one-shot transport, leaving the session broken.
Fix/Workaround: I had to patch dist/server.js locally to construct a fresh McpServer and StreamableHTTPServerTransport per request, adhering to the MCP SDK's stateless pattern.
Many MCP clients (like Claude Code) default to stdio when adding a server via npx. Because this server specifically uses an Express HTTP listener and the streamable-http transport on 127.0.0.1:3323, standard CLI install commands will cause the client to hang waiting for JSON-RPC frames over stdio.
Suggestion: It would be helpful to add a warning in the README that standard stdio MCP configurations will not work, and explicitly document setting it up as a background service/daemon with the "type": "http" configuration.
My current local workaround:
For anyone else stuck on this, I bypassed npx entirely by installing it globally, patching dist/server.js to fix the transport instance issue, and running it as a background systemd user service mapped as an http MCP resource.