Fix @offlinecreator/mcp stdio exiting at startup

Read an immediate stdio exit as a startup failure

When `@offlinecreator/mcp` disappears as soon as an MCP client launches it, test the package boundary before changing OAuth settings or generation tools. The current public release is `@offlinecreator/mcp@0.1.2`; its immutable manifest declares Node.js 20 or newer and exposes the `offlinecreator-mcp` executable. A client using an older Node runtime can therefore fail before an MCP session exists.

The published entrypoint validates local configuration before it starts the stdio transport. If `OFFLINECREATOR_API_KEY` is absent, blank, or does not begin with an accepted `oc_live_` or `oc_test_` prefix, the package writes a specific message to stderr, sets `process.exitCode` to 1, and never reaches `serveStdio`. That makes Node version, package resolution, and environment forwarding the first three checks. Do not paste a real key into a terminal transcript or support ticket.

Exit before any MCP handshake

Check Node, npx resolution, and required environmentThese conditions are evaluated before the published package starts its stdio server.

Process stays alive but the client reports invalid JSON

Inspect stdout contaminationThat is a protocol-channel problem, not the same failure as an immediate configuration exit.

Process exits when the client closes

Confirm normal stdin EOF shutdownA stdio server is expected to exit promptly after its input stream closes.

Follow the first failing boundary

Start with the exact executable and arguments from the client configuration, not a similar command from your interactive shell. Confirm that the client can resolve both `npx` and Node, and record `node --version` from the same launch context when the client exposes one. Then execute the public package directly with no secret value printed. The documented stdio form is `npx -y @offlinecreator/mcp`, with `OFFLINECREATOR_API_KEY` supplied through the client's environment field.

Interpret the first stable result. “Command not found” points to executable lookup or the client's PATH. An npm resolution or network message occurs before OfflineCreator code runs. A Node engine warning or syntax failure points to runtime compatibility. When the pinned public-package command prints that `OFFLINECREATOR_API_KEY is required`, execution reached the package configuration loader without a non-blank key. Its separate invalid-prefix message means a value arrived but did not begin with `oc_live_` or `oc_test_`; replace or revoke it in the secret configuration rather than exposing it for inspection.

Current MCP debugging guidance also warns that stdio-launched servers often inherit only a limited subset of environment variables unless the client forwards them explicitly. A key that exists in your interactive shell can therefore be absent from the MCP child. Only after the direct command remains alive should you investigate the MCP handshake. This order avoids treating every early process exit as an authentication, client-cache, or server-discovery defect.

1. Runtime

Node 20 or newerUse the version visible to the MCP host, which may differ from the version in an interactive terminal.

2. Resolution

npx can fetch and execute the package binaryThe `-y` option suppresses the install prompt; npx options must precede the package name.

3. Configuration

Required variable reaches the child processConfirm the client's env field forwards OFFLINECREATOR_API_KEY; do not assume shell inheritance.

4. Protocol

The process remains available for MCP messagesMove to stdout and handshake diagnosis only after startup validation succeeds.

Capture stderr without corrupting stdout

In the current MCP stdio binding, the client launches the server as a subprocess, writes newline-delimited JSON-RPC messages to its stdin, and reads newline-delimited JSON-RPC messages from stdout. The server may log UTF-8 text to stderr, while stdout must contain only valid MCP messages. The published OfflineCreator entrypoint follows that split: startup diagnostics and caught errors use stderr, then a successful bare invocation hands control to the SDK's stdio server.

Enable the client's MCP server log or run the exact command in a terminal long enough to capture stderr and the numeric exit code. Keep stdout and stderr separate if your diagnostic tool allows it. A clear key, URL, or configuration error on stderr is actionable even though the client may summarize it as “server exited.” Conversely, a normal informational line on stderr is not itself a protocol failure; the specification explicitly says clients should not assume every stderr message is an error. A July 2026 Adelie desktop-assistant issue reports a project-specific client that discarded child stderr entirely, leaving only an exit status when startup failed—treat that as a host-side hypothesis after the package's own stderr check, not as an OfflineCreator defect.

If startup succeeds but messages fail, remove wrapper banners, shell-profile output, debug `console.log` calls, and any other text that reaches stdout. The MCP TypeScript SDK documentation demonstrates that one ordinary stdout log can precede the initialization response and make the protocol stream invalid. Use stderr for diagnostics.

stdout

MCP JSON-RPC onlyDo not merge banners or debug logs into the protocol channel.

stderr

Startup and diagnostic textCapture from process launch, but interpret the message and exit code together.

exit code

Record the numeric valueIt distinguishes a running server from a startup branch that deliberately reports failure.

Choose the next guide after startup

Use the troubleshooting directory if direct execution reveals an HTTP, OAuth, scope, credit, upload, or generation problem rather than a local process exit. Use the client-schema guide when the command works directly but the host never forwards the expected command, arguments, or environment. Use the missing-tools guide only after the process stays connected and tool discovery completes; tool visibility is downstream of successful startup.

Editorial ownership boundary

This page owns only an immediate local stdio startup exit for `@offlinecreator/mcp`: Node compatibility, public-package resolution, required API-key environment forwarding, early stderr, and protocol-safe output. It does not own remote OAuth connection failures, client-specific schema instructions, missing tools after discovery, or generation failures. Keep it separate only while current public package artifacts support this package-specific decision path.