vouchfx-mcp GitHub
Documentation / VFX-E-1007

VFX-E-1007

Title

HttpTransportConfigurationInvalid

Explanation

The optional HTTP transport was requested, but its configuration is unusable — so the server refused to start and no HTTP listener was opened. This is a startup condition, not a tool result: it is reported as one structured JSON record on stderr with "level":"error" (the same shape every line this server writes takes — see Reading the server's log output), followed by a non-zero exit, because it is discovered before the server can speak MCP to anyone.

Failing closed is the point. Falling back to stdio would leave an operator believing a listener exists when none does, and starting an unauthenticated listener would expose every tool — including the ones that spawn the engine CLI — to anyone who can reach the port. Neither is an acceptable degradation, so the server exits instead.

One code covers the whole transport-configuration surface because the remedy is always the same shape: correct the launch configuration and restart. It is never retryable — nothing about waiting changes it.

Common causes

  • --transport http with the VOUCHFX_MCP_HTTP_TOKEN environment variable unset, empty, or whitespace-only.
  • A bearer token passed as a command-line argument (--bearer-token …), which this server refuses outright rather than honours — see Fixes.
  • A VOUCHFX_MCP_HTTP_TOKEN value shorter than 16 characters, carrying leading or trailing whitespace, or containing non-ASCII or control characters. Padding is refused rather than trimmed so the credential accepted is exactly the one configured; non-ASCII is refused because how a client encodes it in an HTTP header is not well defined and would authenticate inconsistently.
  • An unknown --transport value (only stdio and http are supported); a typo is refused rather than silently treated as stdio.
  • --transport or --urls given with no value following it, or given more than once — a repeated flag is refused rather than resolved first-wins or last-wins, either of which would hand you a configuration you did not write.
  • --urls supplied without --transport http — refused rather than ignored, because an operator who typed a bind address believes a listener exists; the stdio default opens none.
  • A --urls value whose scheme is not http://. https://… is refused rather than silently served as cleartext: this server terminates no TLS.
  • A --urls host that is a NAME rather than a literal IP address (http://localhost:5090 is refused; use http://127.0.0.1:5090). Resolving a name at start time would make the bound interface depend on DNS and hosts-file state at that moment.
  • A --urls value carrying anything beyond the address and the port — a path (http://127.0.0.1:5090/other, and …/mcp too), a query string, a fragment, or user information (http://user:pw@127.0.0.1:5090). A bind endpoint is an address and a port; the extra component would be discarded, and the server would then serve at /mcp on that port regardless — reporting success for a configuration you did not write. A bare trailing slash (http://127.0.0.1:5090/) is the same value as no path at all and stays accepted.

Fixes

  • Set VOUCHFX_MCP_HTTP_TOKEN to a high-entropy secret in the environment that launches the server, then restart. The server reads the token only from this variable.
  • Never pass the token on the command line. A process's arguments are readable by every user on the host (/proc/<pid>/cmdline on Linux, ps, Task Manager), and they leak into shell history and into whatever supervisor or container manifest launched the process. This server refuses a token-shaped argument for that reason rather than accepting one and hoping.
  • Check the --transport value is exactly stdio or http, and that neither it nor --urls appears twice.
  • Use a token of at least 16 printable-ASCII characters with no surrounding whitespace — openssl rand -base64 48 satisfies all three.
  • Write --urls as an absolute http:// URL with a literal IP address, e.g. http://127.0.0.1:5090. For TLS or a hostname, put a reverse proxy in front rather than asking this server for either.
  • Give --urls the address and port only — no path, query, fragment or credentials. The MCP path is fixed at /mcp and is not configurable, so append it to the URL your CLIENT calls (http://127.0.0.1:5090/mcp), never to the one the server binds. Authentication is the Authorization: Bearer header, never user information in the URL.
  • If you did not intend to serve over HTTP at all, omit --transport entirely: stdio is the default and needs no configuration, and every existing host integration (Claude Code, Copilot, Cursor, VS Code) uses it.
  • See the HTTP transport section of the install guide for the full setup, including what the ASP.NET Core runtime requirement means for your machine.