How to beginner · 3 min read

How to test MCP tools without a client

Q: How to test MCP tools without a client

Use the official mcp Python SDK to run a local stdio server that hosts your MCP tool without needing a client. This lets you test tool logic by sending and receiving JSON messages over standard input/output streams.

Quick answer

Use the official mcp Python SDK to run a local stdio server that hosts your MCP tool without needing a client. This lets you test tool logic by sending and receiving JSON messages over standard input/output streams.

PREREQUISITES

Python 3.8+
pip install mcp
Basic knowledge of JSON and command line

Setup

Install the official MCP Python SDK and prepare your environment variables if needed. The mcp package provides utilities to run MCP tools locally without a client.

bash

pip install mcp

Step by step

Run a local stdio server to test your MCP tool. This example shows a minimal MCP tool that echoes received messages. You can run this script and interact with it via standard input/output or pipe JSON messages for testing.

python

import sys
import json
from mcp.server.stdio import stdio_server

# Define a simple handler that echoes back the input message
async def handler(message):
    # message is a dict representing the MCP request
    response = {
        "id": message.get("id"),
        "result": {
            "echo": message.get("params")
        }
    }
    return response

if __name__ == "__main__":
    # Run the stdio server with the handler
    import asyncio
    asyncio.run(stdio_server(handler))

Common variations

Use async handlers to support complex async operations.
Test with JSON files piped into the script for batch testing.
Integrate with other MCP transports like SSE or TCP if needed.

python

import asyncio
from mcp.server.stdio import stdio_server

async def async_handler(message):
    # Simulate async processing
    await asyncio.sleep(0.1)
    return {"id": message.get("id"), "result": {"status": "ok"}}

if __name__ == "__main__":
    asyncio.run(stdio_server(async_handler))

Troubleshooting

If the server does not respond, ensure your input messages are valid JSON and follow MCP protocol.
Check for exceptions in your handler and add logging to diagnose issues.
Use print statements carefully; prefer logging to stderr to avoid corrupting JSON streams.

✅

Key Takeaways

Use the official mcp Python SDK's stdio server to test MCP tools without a client.
Implement an async handler function to process MCP messages and return JSON responses.
Pipe JSON requests to the stdio server script for easy local testing and debugging.

Verified 2026-04

Verify ↗