Overview

The MCP endpoint uses the JSON-RPC 2.0 protocol, which provides a standardized structure for making remote procedure calls. This section covers the framework parameters that are required for every request.

Required Parameters

1. jsonrpc

  • Type: string
  • Required: Yes
  • Value: Must always be "2.0"
  • Description: Identifies the JSON-RPC protocol version
{
  "jsonrpc": "2.0"
}

2. id

  • Type: integer
  • Required: Yes
  • Example: 1, 2, 3, etc.
  • Description: Request identifier that will be echoed back in the response. This helps match requests with their corresponding responses, especially when making multiple concurrent requests.
{
  "jsonrpc": "2.0",
  "id": 1
}

3. method

  • Type: string
  • Required: Yes
  • Value: Must be "tools/call"
  • Description: Specifies the RPC method to invoke. For the MCP endpoint, this is always "tools/call".
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call"
}

4. params

  • Type: object
  • Required: Yes
  • Description: Container object that holds the tool-specific parameters. The structure of this object depends on which tool you’re calling.
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    // Tool-specific parameters go here
  }
}

Complete Structure

Here’s the complete JSON-RPC framework structure:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    // Tool-specific content (see Part 2)
  }
}

Important Notes

  1. Fixed Values: The jsonrpc and method parameters have fixed values that never change.

  2. Request Tracking: The id parameter is crucial for tracking requests. You should increment it for each new request to distinguish between different calls.

  3. Params Container: The params object is where the actual tool configuration goes. This is covered in Part 2: Tool-Specific Parameters.

Example Request

POST /v1/spark-api/mcp
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "chat_gwi",
    "arguments": {
      "prompt": "What are the shopping preferences of millennials?",
      "chat_id": ""
    }
  }
}

Response Format

The response will maintain the same JSON-RPC structure:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    // Tool-specific response data
  }
}

Or in case of an error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request"
  }
}

Next Steps

Once you understand the JSON-RPC framework parameters, proceed to Part 2: Tool-Specific Parameters to learn about the different tools you can call and their specific parameter requirements.