Overview

This tool is an adapter for situations where your MCP client only supports the STDIO protocol, but the target MCP server speaks StreamableHTTP.

Usage

Install

uv add mcp-transcoder

Example MCP client configuration

{
  "mcpServers": {
    "lf-agents": {
      "command": "uvx",
      "args": [
        "mcp-transcoder",
        "--insecure",
        "--timeout",
        "300",
        "--headers",
        "x-api-key",
        "YOUR_API_KEY",
        "https://your_mcp_domain/mcp"
      ]
    }
  }
}

Prerequisites

• The MCP server must support StreamableHTTP.
• Server-Sent Events (SSE) is not supported.

Notes

• If the server requires an API key, you can pass --headers KEY VALUE multiple times.
• If a custom CA certificate is required, specify --ssl-cert-file /path/to/cacert.pem (applies only to the MCP connection). For quick testing, you can set --insecure to skip HTTPS verification. The environment variable SSL_CERT_FILE is also supported, but --ssl-cert-file is recommended so the setting does not affect the entire process.

Timeout settings

• The overall timeout for each request (initialize / list_tools / call_tool, etc.) is 120 seconds by default.
• To change it, specify --timeout SECONDS.
  • Example: uvx mcp-transcoder --timeout 300 https://example/mcp
• The same value is applied to the HTTP client (httpx) timeouts to improve stability for long-running operations.

Command-line options

TLS verification (enterprise CA / self-signed)

• Adding --insecure disables certificate verification to the remote server.
  • Example: uvx mcp-transcoder --insecure --headers x-api-key YOUR_API_KEY https://example/mcp
• Recommended: Keep verification enabled and provide a CA certificate instead.
  • Example: uvx mcp-transcoder --ssl-cert-file /path/to/cacert.pem https://example/mcp
  • Note: --ssl-cert-file is applied only to the httpx client used for the MCP connection. It does not affect uvx dependency resolution (e.g., connections to PyPI).

Tests

uv run pytest -q

uvx cache precautions

To avoid issues caused by stale caches, pass --isolated --no-cache to the uvx command when testing.

URLs

PyPI

https://pypi.org/project/mcp-transcoder/

GitHub

https://github.com/post-class/mcp-transcoder/