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

# MCP Server Overview

> Model Context Protocol reference for ChatGPT Apps SDK integration

## Overview

The Model Context Protocol (MCP) server enables integration with ChatGPT Apps SDK, allowing ChatGPT to search your product catalog and interact with your offerings.

## Base URL

```http theme={null}
https://api.hibonsai.com/mcp
```

## Protocol Version

The MCP server implements protocol version: `2025-03-26`

## Authentication

MCP requests require authentication via API key in the `X-API-Key` header:

```http theme={null}
X-API-Key: YOUR_API_KEY_HERE
```

<Callout color="#0A5B3B" icon="triangle-alert">
  Keep API keys server-side only. Do not expose keys in browser client code.
</Callout>

## Endpoints

### Main MCP Endpoint

```http theme={null}
GET /mcp
```

Server-Sent Events (SSE) initialization.

```http theme={null}
POST /mcp
```

JSON-RPC message handling.

### Messages Endpoint

```http theme={null}
GET /mcp/messages
```

Session initialization for message stream handling.

```http theme={null}
POST /mcp/messages
```

Session-based MCP JSON-RPC message handling.

### Organization-Specific Endpoint

```http theme={null}
GET /mcp/org/{organization_id}/
```

Organization-specific MCP endpoint that uses the organization ID from the URL path.

```http theme={null}
POST /mcp/org/{organization_id}/
```

<CardGroup cols={3}>
  <Card title="MCP (GET + POST)" icon="server" href="/project/api-reference/mcp-server/main-endpoint">
    `GET /mcp` and `POST /mcp`.
  </Card>

  <Card title="Messages (GET + POST)" icon="message-square" href="/project/api-reference/mcp-server/messages-endpoint">
    `GET /mcp/messages` and `POST /mcp/messages`.
  </Card>

  <Card title="Organization (GET + POST)" icon="building-2" href="/project/api-reference/mcp-server/organization-endpoint">
    `GET /mcp/org/{organization_id}/` and `POST /mcp/org/{organization_id}/`.
  </Card>
</CardGroup>

## JSON-RPC Methods

The MCP server implements the following JSON-RPC 2.0 methods:

<CardGroup cols={2}>
  <Card title="initialize" icon="plug" href="/project/api-reference/mcp-server/initialize">
    Initialize the MCP connection.
  </Card>

  <Card title="tools/list" icon="list" href="/project/api-reference/mcp-server/tools-list">
    List available tools.
  </Card>

  <Card title="tools/call" icon="play" href="/project/api-reference/mcp-server/tools-call">
    Execute a tool.
  </Card>

  <Card title="resources/list" icon="database" href="/project/api-reference/mcp-server/resources-list">
    List available resources.
  </Card>

  <Card title="resources/read" icon="file-text" href="/project/api-reference/mcp-server/resources-read">
    Read a resource by URI.
  </Card>
</CardGroup>

## Available Tools

The MCP server provides the following tools:

<AccordionGroup>
  <Accordion title="`search_offerings`">
    Search for products and offerings using natural language queries.

    **Input:**

    * `question` (string, required): The search query or question

    **Output:**

    * Returns search results with products and structured content for widget rendering
  </Accordion>

  <Accordion title="`list_all_offerings`">
    List all available offerings without a search query.

    **Input:** None

    **Output:**

    * Returns all available products
  </Accordion>

  <Accordion title="`get_booking_link`">
    Get a booking link for services or appointments.

    **Input:**

    * `offering_id` (string, required): The ID of the offering

    **Output:**

    * Returns booking URL
  </Accordion>

  <Accordion title="`get_product_link`">
    Get a direct link to a product.

    **Input:**

    * `product_id` (string, required): The product ID

    **Output:**

    * Returns product URL
  </Accordion>

  <Accordion title="`single_product_express_checkout`">
    Initiate express checkout for a single product.

    **Input:**

    * `product_id` (string, required): The product ID

    **Output:**

    * Returns checkout information
  </Accordion>
</AccordionGroup>

## CORS Support

The MCP server supports CORS (Cross-Origin Resource Sharing) with the following headers:

* `Access-Control-Allow-Origin: *`
* `Access-Control-Allow-Methods: GET, POST, OPTIONS`
* `Access-Control-Allow-Headers: Content-Type, Accept, MCP-Protocol-Version, X-API-Key, Origin`

## Error Handling

MCP endpoints return JSON-RPC 2.0 error objects:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": {}
  }
}
```

**Common JSON-RPC error codes:**

* `-32700`: Parse error
* `-32600`: Invalid Request
* `-32601`: Method not found
* `-32602`: Invalid params
* `-32603`: Internal error
* `-32000` to `-32099`: Server-defined errors

## Rate Limiting

API requests are rate limited per organization. If you exceed your rate limit, you'll receive a `429 Too Many Requests` response. Rate limits are configured per customer account. Contact your Customer Success Manager (CSM) for information about your account's rate limits.

## Support

For API support, integration assistance, or to request additional features, contact your Customer Success Manager.