Implementing MCP Tools

Minimal MCP tool definition and server response:

JSON
{
  "capabilities": { "tools": { "listChanged": true } }
}

JSON
{
  "name": "get_weather",
  "title": "Weather Information Provider",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City name or zip code" }
    },
    "required": ["location"]
  }
}

Tool call response (unstructured):

JSON
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "content": [
      { "type": "text", "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy" }
    ],
    "isError": false
  }
}

Progress checklist for implementing an MCP tool-serving capability:

• Declare tools capability (listChanged: true/false) in server capabilities
• Define each tool: name, title, description, inputSchema, optional outputSchema, optional icons, optional annotations
• Validate tool name against naming rules (see below)
• Implement tools/list handler: paginated, deterministic ordering, no per-connection variance (auth-scoped variance is allowed)
• Implement tools/call handler: validate arguments against inputSchema, execute, return content and/or structuredContent
• If outputSchema defined, ensure structuredContent conforms and mirror it in a text content block for backwards compatibility
• If tool requires additional user input mid-call, return resultType: "input_required" with inputRequests and requestState; handle retry with inputResponses
• If tool list can change at runtime, send notifications/tools/list_changed to subscribed clients
• If using Streamable HTTP transport and exposing routable parameters, add x-mcp-header annotations; validate constraints and reject invalid tools client-side

Example 1 — Tool with output schema:

Input: Tool get_weather_data with outputSchema requiring temperature, conditions, humidity.

Output:

JSON
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "resultType": "complete",
    "content": [
      { "type": "text", "text": "{\"temperature\": 22.5, \"conditions\": \"Partly cloudy\", \"humidity\": 65}" }
    ],
    "structuredContent": { "temperature": 22.5, "conditions": "Partly cloudy", "humidity": 65 }
  }
}

Example 2 — Input-required flow (elicitation mid-call):

Input: Client calls get_weather for "New York"; server needs GitHub login first.

Output (server asks for input):

JSON
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "input_required",
    "inputRequests": {
      "github_login": {
        "method": "elicitation/create",
        "params": {
          "mode": "form",
          "message": "Please provide your GitHub username",
          "requestedSchema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": ["name"] }
        }
      }
    },
    "requestState": "eyJsb2NhdGlvbiI6Ik5ldyBZb3JrIn0..."
  }
}

Client retries with a new JSON-RPC id, including inputResponses and requestState.

Example 3 — x-mcp-header for HTTP routing:

Input: Tool parameter region should be mirrored as an HTTP header for load-balancer routing.

Output:

JSON
{
  "region": { "type": "string", "x-mcp-header": "Region" }
}

Call with "region": "us-west1" → client adds header Mcp-Param-Region: us-west1.