Skip to main content

Client-Server Interaction

This section presents a step-by-step walkthrough of an MCP client-server interaction, demonstrating the lifecycle, tool operations, and notifications with JSON-RPC 2.0 messages.

Initialize​

The initialization phase establishes the client-server connection and negotiates supported protocol features. This is the first step in any MCP client-server interaction.

The following example shows how to initialize a product search MCP server in Cursor. The client sends an initialize request to establish the connection and negotiate supported features, protocol version, and capabilities.

    {
      "method": "POST",
      "url": "/invoke/94c316b3-8aae-4ab5-b19b-8fc1d6b2cb64/mcp",
      "headers": {
        "host": "asia-south1.mcp.boltic.app",
        ...
      },
      "params": {
        "server_id": "94c316b3-8aae-4ab5-b19b-8fc1d6b2cb64"
      },
      "body": {
        "method": "initialize",
        "params": {
          "protocolVersion": "2025-06-18",
          "capabilities": {
            "tools": {}
          },
          "clientInfo": {
            "name": "gideon-metadata-client",
            "version": "1.0.0"
          }
        },
        "jsonrpc": "2.0",
        "id": 0
      },
    }

Key Components of the Initialize Request:

  • method: "initialize": The JSON-RPC method name indicating this is an initialization request
  • protocolVersion: "2025-06-18": The MCP protocol version the client supports. Both client and server must support compatible versions
  • capabilities: An object describing what features the client supports (e.g., tools, resources, prompts, sampling)
  • clientInfo: Metadata about the client, including:
    • name: The client application name (e.g., "gideon-metadata-client")
    • version: The client version (e.g., "1.0.0")
  • jsonrpc: "2.0": The JSON-RPC protocol version being used

Initialize Response:

The server responds with:

  • protocolVersion: The protocol version the server will use (must be compatible with the client's version)
  • capabilities: What features the server supports and exposes
  • serverInfo: Metadata about the server, including:
    • name: The server name (e.g., "TiraBeauty V2")
    • version: The server version (e.g., "1.0.0")

Initialized Notification​

After successful initialization, the client sends an initialized notification to indicate it is ready to receive requests and notifications from the server. This JSON-RPC notification does not include an id field, so the server does not return a response.

"body": {
  "method": "notifications/initialized",
  "jsonrpc": "2.0"
}

Tool Discovery​

Once the connection is established, the client can discover available tools by sending a tools/list request. This request is fundamental to MCP’s tool discovery mechanism — it allows clients to understand which tools are available on the server before attempting to use them.

  {
    "method": "POST",
    "url": "/invoke/94c316b3-8aae-4ab5-b19b-8fc1d6b2cb64/mcp",
    "headers": {
      "host": "asia-south1.mcp.boltic.app",
      ...
    },
    "params": {
      "server_id": "94c316b3-8aae-4ab5-b19b-8fc1d6b2cb64"
    },
    "query": {},
    "body": {
      "method": "tools/list",
      "jsonrpc": "2.0",
      "id": 1
    },
    "timestamp": "2025-12-11T07:17:19.120Z",
    "protocol_version": "2025-06-18"
  }`

The response includes a tools array with comprehensive metadata for each available tool. This structure allows servers to expose multiple tools at once while maintaining clear boundaries between functionalities.

Tool Metadata Structure:

Each tool in the response includes the following key fields:

  • name: A unique identifier for the tool within the server's namespace. This serves as the primary key for tool execution and should follow a clear, consistent naming pattern. In the example response, the tool name is t1_mcp_tira_seach_products. Tool names are case-sensitive and must match exactly when calling the tool.

  • title (in annotations): A human-readable display name for the tool that clients can show to users. This provides a friendly name that's easier to understand than the technical tool name.

  • description: A detailed explanation of the tool’s function and appropriate use-cases. This description helps AI models understand the tool's purpose and decide when to invoke it. In the example, the description states: "This workflow enables users to perform a product search on the Tira platform by providing a search query. It supports pagination through the 'pageNo' and 'pageSize' parameters, and allows sorting of results using the 'sortOn' field (e.g., by relevance)."

  • inputSchema: A JSON Schema that defines expected input parameters, enabling type validation and providing clear documentation for required and optional parameters. The schema includes:

    • Parameter names and types (string, number, boolean, object, array)
    • Parameter descriptions
    • Required vs. optional parameters
    • Default values (if applicable)
    • Validation constraints (e.g., min/max values, patterns)

This structured metadata enables AI models to understand available tools, their purposes, and correct usage.

Tool Call​

After discovering available tools, the client can execute them using the tools/call method. This demonstrates how MCP primitives are used in practice, as the client or AI model invokes tools with the appropriate arguments to perform operations.

Example Use Case​

The following example demonstrates a real-world scenario in which a user provides the instruction "Give me a list of top-10 highly rated maroon color lipstick" in Cursor. The AI model interprets the request, identifies the appropriate tool (t1_mcp_seach_products), and invokes it with the correct parameters.

Tool Call

Figure 1: Tool Call in Cursor

Request Structure​

The tool call request uses the exact tool name from the discovery response (t1_mcp_tira_seach_products) rather than a simplified name. The request structure includes several important components:

  • method: "tools/call": The JSON-RPC method indicating this is a tool execution request
  • name: Must match exactly the tool name from the discovery response (t1_mcp_tira_seach_products). This ensures the server can correctly identify which tool to execute. Tool names are case-sensitive.
  • arguments: Contains the input parameters as defined by the tool's inputSchema. In this example:
    • q: "maroon lipstick" (the search query)
    • pageno: "1" (the page number for pagination)
    • sorton: "relevance" (sorting criteria)
    • pagesize: "10" (number of results per page)
  • _meta: Optional metadata, including a progressToken for tracking long-running operations
{
"method": "POST",
"url": "/invoke/94c316b3-8aae-4ab5-b19b-8fc1d6b2cb64/mcp",
"headers": {
  "host": "asia-south1.mcp.boltic.app",
  "x-request-id": "1982...[REDACTED]...7c5a",
  "x-real-ip": "[REDACTED]",
  "x-forwarded-for": "[REDACTED]",
  "x-forwarded-host": "asia-south1.mcp.boltic.app",
  "x-forwarded-port": "80",
  "x-forwarded-proto": "https",
  "x-forwarded-scheme": "https",
  "x-scheme": "https",
  "x-original-forwarded-for": "[REDACTED]",
  "content-length": "207",
  "cf-ray": "9ac3332dabc44433-BOM",
  "accept-language": "*",
  "cdn-loop": "cloudflare; loops=1",
  "accept-encoding": "gzip, br",
  "accept": "application/json, text/event-stream",
  "content-type": "application/json",
  "cf-ipcountry": "[REDACTED]",
  "cf-visitor": "{\"scheme\":\"https\"}",
  "cf-connecting-ip": "[REDACTED]",
  "user-agent": "Cursor/2.0.75 (darwin arm64)",
  "sec-fetch-mode": "cors",
  "mcp-protocol-version": "2025-06-18",
  "x-cloud-trace-context": "83eb...[REDACTED]...77c9/10212825880080022890",
  "via": "1.1 google",
  "x-fynd-trace-id": "[REDACTED]",
  "x-fynd-response-id": "[REDACTED]"
},
"params": {
  "server_id": "94c316b3-8aae-4ab5-b19b-8fc1d6b2cb64"
},
"query": {},
"body": {
  "method": "tools/call",
  "params": {
    "name": "t1_mcp_tira_seach_products",
    "arguments": {
      "q": "maroon lipstick",
      "pageno": "1",
      "sorton": "relevance",
      "pagesize": "10"
    },
    "_meta": {
      "progressToken": "[REDACTED]"
    }
  },
  "jsonrpc": "2.0",
  "id": 2
},
"ip": "[REDACTED]",
"user_agent": "Cursor/2.0.75 (darwin arm64)",
"timestamp": "2025-12-11T07:17:01.766Z",
"protocol_version": "2025-06-18"
}

Response Structure​

The tool call response contains:

  • result: The execution result, which includes:

    • content: An array of content items (typically text or structured data)
    • Each content item has a type (e.g., "text") and the actual data
    • In this example, the response contains a JSON array of product objects with details like name, slug, price, description, and media

  • jsonrpc: "2.0": The JSON-RPC protocol version

  • id: Matches the request ID for correlation

The response demonstrates how MCP enables AI models to retrieve structured data from external systems and present it to users in a natural, conversational format.