This MCP server reproduces and analyzes tool call parallelism for Claude Code when running with and without readOnlyHint annotations. The repository demonstrates that enabling readOnlyHint: true on read-only tools allows parallel dispatch, while omitting it serializes tool execution. Use the docker image provided by this project to run the server in an isolated environment and observe the behavior through the included timing instrumentation and analysis scripts. The tooling setup allows you to execute the server, run timing instrumentation via a proxy, and compare results across configurations to understand how readOnlyHint influences concurrency and IPC overhead.

Prerequisites:

• Docker installed and running
• Node.js installed (for any local tooling in the repo, if applicable)
• Python 3.10+ for analysis scripts
• Git for cloning
• An active ANTHROPIC_API_KEY for API access

Installation steps:

1. Clone the repository: git clone https://github.com/greynewell/mcp-serialization-repro.git cd mcp-serialization-repro

2. Pull and run the Docker image provided by the project: docker pull greynewell/mcp-serialization-repro:latest

   Run (example with an API key placeholder; replace with a real key)

   docker run -i -e ANTHROPIC_API_KEY=your-api-key greynewell/mcp-serialization-repro:latest

3. If you need to install local tooling for analysis (optional but recommended):

   • Install the Python package for MCP tooling: pip install mcpbr
   • Ensure Node.js is installed if you plan to interact with any Node-based utilities in the repo.

4. Run the provided scripts to reproduce results: bash run.sh # Uses Docker to start the MCP server and run test scenarios python analyze.py results/ # Analyze the collected results

5. Optional: explore the code and adjust flags for readOnlyHint to reproduce different conditions, then re-run the pipeline to compare IPC overhead and parallelism.

Notes and tips:

• The experiment highlights that readOnlyHint influences parallelism; ensure your tools are annotated accordingly if you want to observe parallel dispatch in Claude Code.
• The analysis relies on timing instrumentation via a proxy to measure IPC overhead; ensure ANTHROPIC_API_KEY is set for API access.
• If you encounter network or image pull issues, verify Docker daemon status and that you have permission to pull the image used by this project.
• The reproduction uses multiple environments (Docker, local Python, and Node tooling); keep environment variables consistent across runs to avoid skewed results.
• Review the README references for context on the MCP specification and related server-filesystem tooling used in parallel vs serial configurations.