> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fitsociety.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Examples & Payload Reference

> JSON-RPC request examples, protocol payloads, and assistant prompt templates.

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 Emma de Vries been attending their bookings regularly over the past month?"*
* **Credit Balance:** *"Check the credit balance for client 64b64c0f2f5f4c0012345678."*
* **Adding Client Progress Notes:** *"Write a progress note for client 64b64c0f2f5f4c0012345678 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](mailto: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:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2026-07-28",
    "capabilities": {
      "roots": {
        "listChanged": false
      }
    },
    "clientInfo": {
      "name": "my-ai-client",
      "version": "1.0.0"
    }
  }
}
```

**Response:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2026-07-28",
    "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:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
```

**Response:**

```json theme={null}
{
  "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:**

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

**Response:**

```json theme={null}
{
  "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\": \"64b64c0f2f5f4c0012345678\",\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": "64b64c0f2f5f4c0012345678",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@example.com",
          "relationship": {
            "status": "active"
          }
        }
      ]
    },
    "isError": false
  }
}
```