Examples & Payload Reference - FITsociety Developer APIs

Here you can find concrete examples of JSON-RPC requests, protocol handshakes, and templates of questions coaches can ask their AI assistant.

Example Prompts for AI Assistants

Once connected, a coach can interact with the assistant using natural English. The assistant translates these questions into tool calls.

Client Search: “Search for clients named John in my database.”
Booking Adherence: “Has client client_9823 been attending their bookings regularly over the past month?”
Credit Balance: “Check the credit balance for client client_8821.”
Adding Client Progress Notes: “Write a progress note for client client_123 stating that we adjusted their squat form and they completed 3 sets of 10 reps.”
Checking Nutrition Logs: “Summarize John’s food logs and macro intake for yesterday.”
Creating a New Client: “Add a new client named Sarah Jenkins with email sarah@jenkins.com.”

JSON-RPC 2.0 Payload Examples

All payloads are sent as a POST request to https://mcp.fitsociety.io/mcp/v1 with Content-Type: application/json.

1. The `initialize` Handshake

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "roots": {
        "listChanged": false
      }
    },
    "clientInfo": {
      "name": "my-ai-client",
      "version": "1.0.0"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "tools": {
        "listChanged": false
      }
    },
    "serverInfo": {
      "name": "fitsociety-company-mcp",
      "title": "FITsociety MCP",
      "version": "1.0.0",
      "description": "FITsociety MCP tools for approved company/coach or client AI access. All data is scoped through the connected grant."
    },
    "instructions": "Tools are scoped to one grant. Write tools are available only when the grant is not read-only and the exact write tool was approved. Authenticate tool calls with Authorization: Bearer <FITsociety MCP key or OAuth access token>."
  }
}

2. Requesting the Available Tools (`tools/list`)

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "search_clients",
        "title": "Search clients",
        "description": "Search the company's client list by name or email. Returns a paginated list of client summaries including relationship status and their clientId. Use get_client to get the full profile.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Optional search query string, matched against first name, last name, or email.",
              "maxLength": 200
            },
            "page": {
              "type": "integer",
              "minimum": 1
            },
            "limit": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          },
          "additionalProperties": false
        },
        "annotations": {
          "title": "Search clients",
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        }
      }
    ]
  }
}

3. Calling a Tool (`tools/call`)

Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_clients",
    "arguments": {
      "query": "John",
      "page": 1,
      "limit": 10
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 1 client(s); returning page 1 (1 item(s)).\n\n{\n  \"page\": 1,\n  \"limit\": 10,\n  \"total\": 1,\n  \"hasMore\": false,\n  \"clients\": [\n    {\n      \"clientId\": \"client_5f812b7a9b34...\",\n      \"firstName\": \"John\",\n      \"lastName\": \"Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"relationship\": {\n        \"status\": \"active\"\n      }\n    }\n  ]\n}"
      }
    ],
    "structuredContent": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "hasMore": false,
      "clients": [
        {
          "clientId": "client_5f812b7a9b34...",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@example.com",
          "relationship": {
            "status": "active"
          }
        }
      ]
    },
    "isError": false
  }
}

​Example Prompts for AI Assistants

​JSON-RPC 2.0 Payload Examples

​1. The initialize Handshake

​2. Requesting the Available Tools (tools/list)

​3. Calling a Tool (tools/call)

Example Prompts for AI Assistants

JSON-RPC 2.0 Payload Examples

1. The `initialize` Handshake

2. Requesting the Available Tools (`tools/list`)

3. Calling a Tool (`tools/call`)