mcp-tuning

A script-first MCP debugging/testing library for Jupyter notebooks and plain Python scripts.

It is designed to help you iterate on MCP servers (implemented in any language) by providing a small, synchronous client API:

• Connect via stdio (subprocess), http, or sse
• Explore: tools / resources / prompts
• Call tools with JSON arguments
• Save/replay input-only cases (tool + args)
• Export logs / history / last result as JSON for repeatable debugging

Start with examples/notebooks/01_mcp_inspector_demo.ipynb.

Requirements

• Python 3.12+
• uv

Install (uv)

uv sync
uv sync --extra notebook --extra test

Run (Jupyter)

uv run jupyter lab

Quickstart (stdio)

Prefer argv lists for stdio servers (avoids shell quoting issues) and make sure the server runs in an environment that has its dependencies installed.

from mcp_tuning import connect_stdio

# Example 1: connect to the built-in mock server (minimal dependencies)
import sys
c = connect_stdio([sys.executable, "src/mcp_tuning/_mock_server.py"])

print(c.server_info())
print([t.name for t in c.tools()])
print(c.call("add", {"a": 1, "b": 2}).result)
c.close()

Connect to the FastMCP example server (requires mcp installed in the interpreter that runs the server):

from mcp_tuning import connect_stdio

c = connect_stdio([".venv/Scripts/python.exe", "examples/servers/simple_stdio_server.py"])
print([t.name for t in c.tools()])
print(c.call("add", {"a": 1, "b": 2}).result)
c.close()

Public API Reference

The public API is intentionally small and exported at the top-level mcp_tuning package.

Connect functions

• connect_stdio(command, *, cwd=None, env=None) -> Client
  • command: list[str] (recommended) or str
  • defaults to running the subprocess with the repo root as cwd (more reliable in notebooks)
• connect_http(rpc_url, *, headers=None) -> Client
• connect_sse(*, sse_url, rpc_url, headers=None) -> Client

Client

Client (alias: MCPClient) is the main entry point for notebooks and scripts.

• Lifecycle

  • close()
  • server_info() -> dict | None

• Explore

  • tools(timeout_s=30) -> list[ToolItem]
  • tool(name, timeout_s=30) -> ToolItem | None
  • resources(timeout_s=30) -> list[ResourceItem]
  • read_resource(uri, timeout_s=60) -> Any
  • prompts(timeout_s=30) -> list[PromptItem]
  • get_prompt(name, arguments=None, timeout_s=60) -> Any

• Call

  • call(name, arguments=None, timeout_s=60) -> CallResult
  • last() -> CallResult | None

• Rendering (notebook-friendly)

  • show(obj, mode='auto'|'json'|'text'|'markdown', compact=True, max_depth=5, max_items=60) -> None
  • dumps(obj, compact=True, max_depth=5, max_items=60) -> str

• Cases (input-only: tool + args)

  • save_case(tool, arguments, note=None, root=None) -> Path
  • cases(root=None) -> list[Path]
  • load_case(path) -> CallCase
  • replay_case(case, timeout_s=60) -> CallResult
  • replay_case_path(path, timeout_s=60) -> CallResult

• Exports

  • export_logs(root=None) -> Path
  • export_history(root=None) -> Path
  • export_last(root=None) -> Path

Models (data types)

The following types are also exported for type hints and inspection:

• ToolItem, ResourceItem, PromptItem
• CallCase (stores tool + args + metadata)
• CallResult (includes ok/result/error/stderr_tail/ts)
• LogEvent

Files & Folders

• examples/notebooks/: example notebooks (script-first)
• examples/servers/: example MCP servers
• docs/: detailed documentation (start at docs/index.md)
• cases/: saved cases (*.json)
• exports/: exported logs/history/results (*.json)

Troubleshooting

• Timeouts usually mean the server did not start correctly (missing deps, wrong executable, wrong paths).
  • For the FastMCP example, run the server with .venv/Scripts/python.exe.
• Notebook working directories are often not the repo root; this library defaults stdio subprocess cwd to the repo root.
• On timeouts, the error message includes a stderr tail (stdio) to help you debug server startup failures.

Tests

python -m pytest