GuestKie MCP API Documentation

1. Protocol Specification

The GuestKie MCP server implements the 2026-07-28 revision of the Model Context Protocol over stateless Streamable HTTP.

Required Request Headers

Every POST request to /mcp must declare routing headers:

Required _meta in Request Body

Every request payload must include client capabilities and protocol version within params._meta:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

2. Authentication

The GuestKie MCP server supports two distinct authorization pathways: long-lived tenant bearer tokens and standards-compliant OAuth 2.1 authorization code flows with PKCE.

3. Scopes & Tool Catalog Filtering

GuestKie strictly enforces least-privilege advertising. When a client requests tools/list:

• Scope-Based Filtering: Only tools matching the token's granted scopes are advertised. Write-scoped tools are never advertised to a read-only token.
• Unwired Tool Suppression: Tools that do not yet have an active backend implementation (wired: false) are hidden by default. They can be inspected by passing includeUnwired: true in the request params.
• Canonical Naming: Every tool exposes one canonical snake_case name formatted as ${module}_${action} (e.g. reservations_list_reservations, properties_list_properties). Legacy short aliases (list_reservations, get_reservation) are hidden from the catalog by default to eliminate duplicates, but remain callable via tools/call for one release.

Available Scopes

4. The Bookkeeper Read-Only Profile

For accounting, tax reconciliation, and bookkeeping clients, the 687-tool full catalog is noisy and unneeded. GuestKie provides a dedicated Bookkeeper Profile (bookkeeper) that curates a strictly read-only catalog under 80 tools with zero write-scoped tools.

Core Bookkeeper Tools Table

5. Credential Redaction & Security Policy

GuestKie strictly enforces automated credential and secret redaction at all protocol boundaries. In alignment with GuestKie's access security policy:

6. JSON-RPC 2026-07-28 Examples

POST /mcp HTTP/1.1
Host: mcp.guestkie.com
Authorization: Bearer gkmcp_ABC123...
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "server/discover",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "supportedVersions": ["2026-07-28"],
    "capabilities": { "tools": { "listChanged": false } },
    "instructions": "GuestKie tenant MCP endpoint. Tools are scoped to the bearer token used to authenticate.",
    "ttlMs": 3600000,
    "cacheScope": "public",
    "_meta": {
      "io.modelcontextprotocol/serverInfo": {
        "name": "guestkie-mcp",
        "version": "0.1.0"
      }
    }
  }
}

POST /mcp HTTP/1.1
Host: mcp.guestkie.com
Authorization: Bearer gkmcp_ABC123...
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/list
Mcp-Profile: bookkeeper
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {
    "profile": "bookkeeper",
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

POST /mcp HTTP/1.1
Host: mcp.guestkie.com
Authorization: Bearer gkmcp_ABC123...
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: transactions_list_transactions_for_tenant
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "transactions_list_transactions_for_tenant",
    "arguments": {
      "limit": 50,
      "source": "all"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

7. Server Endpoints

8. Error Codes & Troubleshooting