mobius-mcp-stdio-invocation

name

mobius-mcp-stdio-invocation

description

Invoke any MCP (Model Context Protocol) server directly from the CLI via stdio JSON-RPC, with no Claude Code / harness dependency. Use when you need to call MCP tools (web search, image understanding, file ops, custom tools) from a shell script, CI job, or a session that doesn't have the MCP auto-loaded. Covers: installing `uv`/`uvx` (or `npx`), spawning the server, the JSON-RPC 2.0 handshake, `tools/list` discovery, `tools/call` invocation, and result parsing — with the MiniMax `minimax-coding-plan-mcp` package as a verified worked example.

MCP stdio invocation from the CLI

MCP servers speak JSON-RPC 2.0 over stdio — the server's stdin is the request stream, stdout is the response stream, stderr is for human logs. Any process that can spawn a subprocess and read/write its stdio can be an MCP client. You do not need Claude Code, Cursor, or any harness to use them.

This SKILL is the recipe for "I want to call MCP tool X, from a shell, right now."

When to use

• Your session has no mcp__* tools registered (e.g. a CI runner, a worker session, an ad-hoc bash turn).
• You want to script MCP tool calls in a pipeline.
• The MCP server supports stdio transport (most do; SSE/HTTP transports are a separate path).
• You want to verify an MCP works before registering it with claude mcp add.

If the server is already loaded into your harness as mcp__server__tool, just call it directly — don't reinvent the stdio pipe.

Protocol summary (MCP 2024-11-05)

Three-step handshake, then arbitrary tools/list / tools/call:

1.  request  initialize          → response with serverInfo + capabilities
2.  notify    notifications/initialized  (no response, just a fire-and-forget)
3.  request  tools/list          → response with tool schemas
    request  tools/call          → response with content blocks

All frames are single-line JSON. One request → one response, matched by id. Notifications (no id) get no reply. Use select() or non-blocking reads to avoid deadlock when the server logs to stderr.

Frame shapes

// request
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}

// notification
{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}

// success response
{"jsonrpc":"2.0","id":1,"result":{...}}

// error response
{"jsonrpc":"2.0","id":1,"error":

tools/call result is result.content — an array of content blocks. Text blocks are stringified JSON that you must re-parse:

{"result":{"content":[{"type":"text","text":"{\n  \"organic\": [...]\n}"}]}}

Install the launcher

MCP servers are usually published as a Python or Node package with a command entry point.

Ecosystem	Install	Spawn command
PyPI (uvx)	curl -LsSf https://astral.sh/uv/install.sh | sh (one-time)	uvx --from <pkg> <entrypoint> -y
npm (npx)	comes with Node	npx -y <pkg>

uvx and npx both (1) create an ephemeral venv/cache, (2) install the package on first run, (3) execute the entrypoint, (4) clean up on exit. The -y flag auto-confirms any "install?" prompt.

After installing uvx, verify with which uvx → expect a path like /home/<user>/.local/bin/uvx.

Generic Python harness

Drop this into a script and point it at any stdio MCP server. Replace COMMAND, ENV, and the tool name you want to call.

# mcp_invoke.py — minimal MCP stdio client
import json, os, subprocess, sys, time, select

COMMAND = ["uvx", "--from", "<PACKAGE>", "<ENTRYPOINT>", "-y"]  # e.g. uvx --from minimax-coding-plan-mcp minimax-coding-plan-mcp -y
ENV_OVERRIDES = {  # MCP-specific env vars; the server reads these
    # "API_KEY_ENV_NAME": "sk-...",
    # "BASE_URL_ENV_NAME": "https://...",
}

def call_tool(name, arguments, *, timeout=60):
    env = os.environ.copy()
    env.update(ENV_OVERRIDES)

    proc = subprocess.Popen(
        COMMAND,
        stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
        env=env, text=True, bufsize=1,
    )

    def send(req):
        proc.stdin.write(json.dumps(req) + "\n"); proc.stdin.flush()
    def recv(timeout_s=timeout):
        end = time.time() + timeout_s
        while time.time() < end:
            r,_,_ = select.select([proc.stdout], [], [], 0.5)
            if r:
                line = proc.stdout.readline()
                if line: return json.loads(line)
        raise TimeoutError("no MCP response")

    try:
        send({"jsonrpc":"2.0","id":1,"method":"initialize","params":{
            "protocolVersion":"2024-11-05",
            :{},
            :{:,:},
        }})
        recv()                                

        send({:,:,:{}})

        send({:,:,:,:{
            : name, : arguments,
        }})
         recv()
    :
        proc.terminate()
        : proc.wait(timeout=)
         subprocess.TimeoutExpired: proc.kill()

 __name__ == :
    result = call_tool(, {: })
    (json.dumps(result, ensure_ascii=, indent=))

Discovery variant: list tools first

If you don't know the tool names, swap the tools/call for tools/list:

send({"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}})
tools_resp = recv()
for t in tools_resp["result"]["tools"]:
    print(t["name"], "—", t.get("description","")[:80])

Then drive tools/call based on what you see.

Worked example: MiniMax Token Plan MCP

Verified end-to-end on 2026-06-10 in an imac-test session that had no MCP auto-loaded.

Field	Value
Package	minimax-coding-plan-mcp (PyPI)
Server	Minimax v1.27.2, protocol 2024-11-05
Env vars	MINIMAX_API_KEY (required), MINIMAX_API_HOST (default https://api.minimaxi.com), MINIMAX_MCP_BASE_PATH (local output dir, must exist + writable), MINIMAX_API_RESOURCE_MODE (url / local)
Tools	web_search(query), understand_image(prompt, image_url)

Spawn command:

MINIMAX_API_KEY="sk-cp-..." \
MINIMAX_API_HOST="https://api.minimaxi.com" \
MINIMAX_MCP_BASE_PATH="/tmp/mcp-out" \
MINIMAX_API_RESOURCE_MODE="url" \
uvx --from minimax-coding-plan-mcp minimax-coding-plan-mcp -y

Call shape (web_search):

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
  "name":"web_search",
  "arguments":{"query":"<3-5 keywords, include date for time-sensitive>"}
}}

Response shape (web_search result is a stringified JSON inside content[0].text):

{
  "result": {
    "content": [
      {"type": "text", "text": "{\"organic\":[{\"title\":...,\"link\":...,\"snippet\":...,\"date\":...}],\"related_searches\":[...],\"base_resp\":{...}}"}
    ]
  }
}

So: r["result"]["content"][0]["text"] → json.loads(...) → organic[].

Real latency observation: web_search for a current-events query round-trips in 5–15 s (it's a search backend call, not local compute).

Recipe: register for future sessions (optional)

Once you've verified the server works over stdio, you can pin it to user-level Claude Code so future sessions auto-load it. The update-config skill (or claude mcp add on the CLI) writes ~/.claude.json:

claude mcp add -s user MiniMax \
  --env MINIMAX_API_KEY=sk-cp-... \
  --env MINIMAX_API_HOST=https://api.minimaxi.com \
  -- uvx minimax-coding-plan-mcp -y

After this, new sessions get mcp__MiniMax__web_search and mcp__MiniMax__understand_image tools. The current session won't pick it up — MCPs are loaded at Claude Code startup.

Common pitfalls

• No response, then timeout — server is waiting for the initialized notification and you didn't send it. Always send the notification between initialize and any other request.
• Method not found (-32601) — wrong protocol version in initialize. 2024-11-05 is the current default; some older servers want 2024-10-07 or 2025-03-26. Check the server's docs.
• Response looks like a dict, not a list — you got a result object; the actual tool output is result.content[0].text (always a string, often JSON inside).
• Stderr is silent — many MCP servers log useful info (retry counts, rate limits) to stderr. Tee it: stderr=subprocess.PIPE and read on timeout.
• Env var not picked up — servers usually read env only at startup. Set them before spawning. Mutating os.environ after Popen is too late.
• uvx not found — install with the one-liner above; it lands in ~/.local/bin/uvx, which is not on every shell's default PATH. Prefix export PATH="$HOME/.local/bin:$PATH".
• Server hangs after first call — JSON-RPC needs newline-delimited frames. text=True, bufsize=1 and a "\n" after every json.dumps(req) are mandatory.
• Output files cluttering the repo — MINIMAX_MCP_BASE_PATH defaults to ./.trash for the MiniMax MCP; point it at /tmp/... or your .imac/scratch/ to keep the project clean.
• Auth key leakage in logs — many MCP servers log the env var name (not the value) on startup. Fine, but don't set -x the parent shell if the value is sensitive.

Pattern: shell-only quick call

If you don't want a Python script, you can drive the JSON-RPC stream straight from bash with jq + heredocs. Less robust (no error handling) but useful for one-offs:

KEY="sk-cp-..."
{
  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli","version":"0"}}}'
  echo '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}'
  echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"web_search","arguments":{"query":"today news"}}}'
  sleep 20
} | MINIMAX_API_KEY="$KEY" MINIMAX_API_HOST="https://api.minimaxi.com" \
  MINIMAX_MCP_BASE_PATH="/tmp/mcp-out" \
  uvx --from minimax-coding-plan-mcp minimax-coding-plan-mcp -y \
  2>/dev/null | head -1

The first line of stdout is the initialize response; you'll need a longer-lived pipe (e.g. coproc or a temp file per request) to map request ids to responses properly. Use the Python harness for anything non-trivial.

Generalizing beyond MiniMax

The exact same recipe works for any stdio MCP server. Substitutions:

What you change	Where
COMMAND list	["uvx", "--from", "<pkg>", "<entry>", "-y"] or ["npx", "-y", "<pkg>"]
ENV_OVERRIDES	whatever env vars the server's docs list (auth keys, base URLs, output paths)
name in tools/call	the tool name from tools/list
arguments in tools/call	the JSON schema from tools/list

If tools/list returns nested argument schemas (objects, enums, arrays), feed them straight into the arguments dict — the harness serializes them for you.

When not to use this

• The MCP server is HTTP/SSE transport, not stdio. The handshake is different; you'll need an HTTP client.
• The server requires OAuth / dynamic client registration. Stdio servers usually take a static API key; OAuth servers (e.g. some Google/Microsoft ones) need a token-refresh loop.
• The tool produces binary outputs (audio, video, images). Stdio JSON-RPC can carry base64, but it's clumsy — for big media, prefer the underlying HTTP API directly.
• You're already in a session where the MCP is auto-loaded. Just use the registered mcp__server__tool — no subprocess needed.