Tool Handler

The handler's primary duty is to receive and validate the input arguments provided by the client against the tool's defined JSON Schema. This ensures type safety and data integrity before execution. For example, a get_weather tool handler would validate that the city parameter is a string and the date is in ISO 8601 format. Failed validation must return a clear error to the client without executing business logic.

The handler encapsulates all logic for interacting with external APIs, databases, or internal systems. It is responsible for:

• Authentication: Managing credentials (API keys, OAuth tokens) securely, often fetched from a vault.
• Network Calls: Executing HTTP requests (REST, GraphQL), database queries, or gRPC calls.
• Protocol Translation: Converting between the MCP's standardized JSON and the target system's native data format.

After execution, the handler must format the result into the structured output expected by the MCP client, typically a JSON object. This includes:

• Success Responses: Packaging data (e.g., {"temperature": 22, "unit": "C"}) with appropriate MIME types.
• Error Responses: Returning standardized error objects with codes and human-readable messages for client-side handling, distinct from system-level transport errors.
• Content Type Declaration: Specifying text/plain, application/json, or image/png so the client can interpret the result correctly.

Handlers for tools that modify state (e.g., create_ticket, update_record) must be designed with idempotency where possible, ensuring repeated calls with the same inputs produce the same system state. The handler manages side effects, which may involve:

• Transaction Management: Rolling back database changes on failure.
• Event Emission: Logging actions or publishing events to a message bus for downstream systems.
• Atomic Operations: Ensuring a multi-step process either completes fully or not at all.

A production-grade handler implements comprehensive logging and telemetry. This is critical for debugging, security, and compliance. Responsibilities include:

• Structured Logging: Recording each invocation with a correlation ID, input parameters (sanitized of secrets), execution duration, and outcome.
• Metric Emission: Tracking counts of invocations, error rates, and latency for monitoring dashboards.
• Audit Trails: Creating immutable records of actions performed, especially for tools that access or modify sensitive data, to satisfy regulatory requirements.

The handler is responsible for the proper lifecycle of any resources it acquires during execution to prevent leaks and ensure system stability. This involves:

• Closing Connections: Explicitly closing database connections, HTTP sessions, or file handles after use.
• Memory Management: Ensuring large intermediate data objects are garbage-collected.
• Timeout Enforcement: Respecting configured execution timeouts to prevent hanging processes from blocking the MCP server, often by using cancellation tokens or context deadlines.

An MCP Tool is the formal, client-facing definition of an executable function exposed by an MCP server. It acts as the contract between the client and the handler, comprising:

• A unique name for invocation.
• A description explaining its purpose to the AI.
• An inputSchema (JSON Schema) defining the exact structure, types, and validation rules for the arguments the handler expects.

The Tool Definition is what the AI client sees and uses to construct a call; the Tool Handler is the server-side code that fulfills it.

Tool Invocation is the event that triggers the Tool Handler. It is the JSON-RPC request sent from the MCP client to the server, containing:

• The name of the tool to execute.
• The arguments object, which must conform to the tool's defined input schema.
• A unique requestId for tracking the request-response pair.

This invocation payload is deserialized by the MCP server framework and passed as parameters to the registered Tool Handler function for execution.

JSON-RPC is the lightweight remote procedure call protocol that forms the messaging layer of MCP. All communication between client and server—including tool invocations and handler responses—is structured as JSON-RPC messages.

For a Tool Handler, this means:

• It is invoked via a JSON-RPC request method.
• It must return its result within a JSON-RPC success response.
• Any errors must be formatted as a JSON-RPC error response with standardized codes.

This protocol ensures strict, language-agnostic interoperability for the handler's inputs and outputs.

Schema Validation is the pre-execution safety check performed by the MCP server before a request reaches the Tool Handler. The server validates the arguments object from the invocation request against the tool's declared inputSchema (JSON Schema).

This ensures:

• Required parameters are present.
• Data types (string, number, array, object) are correct.
• Any custom constraints (e.g., string patterns, number ranges) are met.

If validation fails, the invocation is rejected with an error, and the Tool Handler is never called, protecting it from malformed or malicious input.

A Tool Provider is the server-side component or interface responsible for managing the lifecycle of tools within an MCP server. Its core responsibilities include:

• Registering one or more Tool Definitions with the MCP server.
• Mapping each tool definition to its corresponding Tool Handler function.
• Receiving validated invocation requests from the server's transport layer.
• Executing the correct handler with the provided arguments.
• Packaging the handler's return value (or error) into a proper JSON-RPC response.

In many frameworks, you implement a Tool Provider to expose your business logic as tools.

An MCP Transport is the underlying communication channel that carries the JSON-RPC messages between client and server. The Tool Handler is abstracted from this layer, but the transport defines the operational environment.

Common transports include:

• Stdio: Messages exchanged over standard input/output. Handlers are often local, long-running processes.
• SSE (Server-Sent Events): HTTP-based, allowing remote servers. Handlers must be stateless and handle connection lifecycles.
• Named Pipes / Unix Sockets: Used for inter-process communication on a single host.

The transport dictates how the server is launched and how messages are framed, but the handler's logic remains consistent across them.