Troubleshoot Jelly MCP Connections

Observed symptom → diagnosis → resolution

Run commands from the Jelly repository root. Do not paste tokens or personal browser data into issue reports.

MCP service does not respond

Likely cause: The user service is stopped, dependencies are missing, or the configured loopback port differs.

Diagnostic check:

systemctl --user status jelly-mcp.service
journalctl --user -u jelly-mcp.service -n 50 --no-pager

Resolution: Start the service with the configured installer or resolve the logged error; verify the configured address.

Verification: Run curl http://127.0.0.1:8787/health and check for status: ok.

Remote profile rejects local startup

Likely cause: The checked-in chatgpt remote-http profile requires a real HTTPS JELLY_PUBLIC_URL.

Diagnostic check:

grep -A3 "\[\[mcp.connections\]\]" config/jelly.toml

Resolution: Use the hosting wizard to establish an HTTPS origin, or remove the remote ChatGPT profile for local-only operation.

Verification: Restart the MCP process and confirm /health returns ok.

HTTP 401 Unauthorized

Likely cause: The bearer token is absent or mismatched, or an OAuth access token has expired or has not been issued.

Diagnostic check:

curl -i http://127.0.0.1:8787/mcp

Resolution: Load JELLY_MCP_TOKEN from the local .env without printing it, or complete OAuth. Do not use the bootstrap secret as a normal MCP token.

Verification: An authenticated tools/list or browser-schema tools/call returns a JSON-RPC result.

HTTP 403 on dashboard or status

Likely cause: Ordinary OAuth credentials do not grant operator diagnostics.

Diagnostic check:

curl -i http://127.0.0.1:8787/status.json

Resolution: Use the configured owner pairing flow or authorized bootstrap/static bearer token.

Verification: Authorized /status.json succeeds; ordinary OAuth remains forbidden.

Browser tool fails with browser_unavailable

Likely cause: Chromium is not running, CDP is unreachable, or sandbox/container restrictions prevented startup.

Diagnostic check:

command -v chromium
systemctl --user status jelly-browser.service
./scripts/dev.sh browser diagnose --engine docker --container jelly-chromium-1

Resolution: For native mode, verify Chromium at /usr/bin/chromium and inspect service logs. For a container, inspect engine logs and the requested sandbox/restrictions; consider different kernel namespace/seccomp settings or explicit operator-selected alternative options. For remote address mode, verify CDP routing and credentials/tunnel. Jelly never changes security preferences silently.

Verification: CDP connectivity and tool calls succeed. This does NOT prove the effective Chromium sandbox is active; that requires separate verification.

Unknown tool or invalid arguments

Likely cause: The client called an operation outside the active small/large surface or supplied the wrong argument shape.

Diagnostic check:

curl --fail http://127.0.0.1:8787/health

Resolution: Call tools/list to inspect published tools; use browser-schema with action=schema to retrieve semantic operation parameters.

Verification: Repeat the published tool with matching arguments and inspect structuredContent.ok.

Quick Tunnel URL changed

Likely cause: A temporary Cloudflare URL was regenerated, changing OAuth issuer and protected resource.

Diagnostic check:

./scripts/dev.sh status

Resolution: Update the client's MCP URL, reconnect, and repeat OAuth authorization against the new origin.

Verification: The client authenticates against the new HTTPS origin and completes tools/list.

Still blocked?

Read the setup troubleshooting guide, then open a bug report with the failing command, sanitized output, operating system and commit. For security reports, contact the maintainer privately.