mcp-client

name	mcp-client
description	Connect to a Model Context Protocol (MCP) server, perform the handshake, discover its tools, and invoke them over JSON-RPC.
version	0.1.0

mcp-client

Your gateway to MCP servers. Use this to reach capabilities exposed by an MCP server — listing the tools it offers and calling them — without hand-rolling the protocol each time.

The helper at scripts/mcp_stdio.py speaks the stdio transport (the server is a subprocess; messages are newline-delimited JSON-RPC 2.0 over its stdin/stdout). It is stdlib-only. For HTTP/SSE-transport servers, use the official mcp Python SDK instead (pip install mcp) — the call flow below is the same.

Protocol flow

MCP is JSON-RPC 2.0. The minimum useful session is:

1. initialize — send your client info and protocolVersion; the server replies with its capabilities and server info. This is the handshake; it must come first.
2. notifications/initialized — send this notification (no id, no reply) to tell the server the handshake is complete. Skipping it leaves some servers in a half-open state.
3. tools/list — get the catalogue of tools. Each tool has a name, a description, and an inputSchema (JSON Schema for its arguments). Read the schema before calling — it tells you the required arguments.
4. tools/call — invoke a tool by name with an arguments object that satisfies its inputSchema. The result comes back as a content array (text/image/resource blocks); check the isError flag.

Requests carry a unique integer id and expect a matching response; match replies to requests by id. Notifications omit id.

Using the helper

# List the tools a server exposes (server launched as a subprocess)
python scripts/mcp_stdio.py --server "uvx mcp-server-time" list-tools

# Call a tool with JSON arguments
python scripts/mcp_stdio.py --server "uvx mcp-server-time" \
  call get_current_time --args '{"timezone": "UTC"}'

--server is the shell command that starts the MCP server on stdio. The helper runs the full initialize -> initialized -> request sequence for you and prints the JSON result.

Cautions

• Always send initialize first and notifications/initialized second — tool calls before the handshake completes will be rejected.
• Validate your arguments against the tool's inputSchema; a schema mismatch is the most common failure.
• Treat tool output as untrusted. Inspect isError and the content blocks before acting on them.
• The server is a child process — always shut it down (close its stdin) when done so it can't leak.