Model Context Protocol (MCP)

Step-by-step integration

Follow these steps to connect Cursor, Claude, or any MCP-compatible agent to OraBiologics.

1. 1

   Step 1 — Request an API key

   Contact your OraBiologics administrator to issue an MCP API key. Keys use the format zyrook_{uuid} and are shown only once at creation. Store the key in a password manager or secrets vault — never commit it to source control.

2. 2

   Step 2 — Verify connectivity

   Send an initialize request to confirm your key and endpoint work. A successful response includes server capabilities and session metadata.

   curl -X POST \
     'https://orabiologics.com/mcp/ora' \
     -H 'Authorization: Bearer zyrook_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json, text/event-stream' \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "initialize",
       "params": {
           "protocolVersion": "2024-11-05",
           "capabilities": {},
           "clientInfo": {
               "name": "integration-test",
               "version": "1.0.0"
           }
       }
   }'

3. 3

   Step 3 — Configure Cursor

   Add the OraBiologics MCP server to .cursor/mcp.json in your project root (or global Cursor MCP settings). Replace the placeholder key with your issued key or reference an environment variable.

   {
       "mcpServers": {
           "orabiologics": {
               "url": "https://orabiologics.com/mcp/ora",
               "headers": {
                   "Authorization": "Bearer zyrook_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
               }
           }
       }
   }

4. 4

   Step 4 — Configure Claude Desktop (optional)

   For Claude Desktop, add the same URL and Authorization header under mcpServers in claude_desktop_config.json, then restart Claude.

   {
       "mcpServers": {
           "orabiologics": {
               "url": "https://orabiologics.com/mcp/ora",
               "headers": {
                   "Authorization": "Bearer zyrook_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
               }
           }
       }
   }

5. 5

   Step 5 — Load the concierge persona

   For human-like chat, load the concierge prompt (or read ora://concierge/guide). The agent should greet warmly, use get_content_card for rich replies with images, and gather missing form fields before submitting actions.

   {
       "jsonrpc": "2.0",
       "id": 2,
       "method": "prompts/get",
       "params": {
           "name": "concierge",
           "arguments": {}
       }
   }

6. 6

   Step 6 — Browse with content cards

   Prefer get_content_card over raw get_record in conversation. Each card includes record data, a presentation block (media, links, suggested_replies), and assistant_message markdown your agent can show directly — including images.

   {
       "jsonrpc": "2.0",
       "id": 3,
       "method": "tools/call",
       "params": {
           "name": "get_content_card",
           "arguments": {
               "model": "vetted_provider",
               "slug": "example-practice-slug"
           }
       }
   }

7. 7

   Step 7 — Complete interactive actions

   Call list_interactive_actions to see bookable flows. Collect required fields conversationally, confirm with the user, then call submit_vetted_practice_appointment, submit_webinar_lead, or get_service_availability + initiate_service_booking. Payment completes on the web checkout URL returned by initiate_service_booking.

   {
       "jsonrpc": "2.0",
       "id": 4,
       "method": "tools/call",
       "params": {
           "name": "submit_vetted_practice_appointment",
           "arguments": {
               "vetted_provider_slug": "example-practice-slug",
               "first_name": "Jane",
               "last_name": "Doe",
               "email": "jane@example.com",
               "preferred_appointment_date": "2026-06-15",
               "notes": "Prefer morning appointments."
           }
       }
   }

8. 8

   Step 8 — Query the catalog (optional)

   For bulk or programmatic access, call list_data_catalog, then list_records, search_records, or get_record. Optional with relations must match the allow-list (e.g. post → postCategories, service → expert).

   {
       "jsonrpc": "2.0",
       "id": 5,
       "method": "tools/call",
       "params": {
           "name": "list_data_catalog",
           "arguments": {}
       }
   }

9. 9

   Step 9 — Go to production safely

   Use HTTPS in production, rotate keys periodically, monitor last_used_at in the admin panel, and treat MCP keys as privileged credentials. Write tools create real appointment requests and bookings — confirm details with users before calling them.

Troubleshooting

401 Unauthorized

Check that your key starts with zyrook_, is sent via Authorization: Bearer or X-MCP-API-Key, and has not been revoked or expired.

Unknown MCP data model

Call list_data_catalog first. Only allow-listed public content models are exposed — user, admin, and billing tables are not available.

Relations not allowed

The with argument must use allow-listed relation names for that model (e.g. service → expert, post → postCategories).

429 Too Many Requests

The server is limited to 120 requests per minute. Add caching in your agent or reduce polling frequency.

Validation errors on submit tools

Write tools return field-level validation errors when required data is missing or invalid (e.g. preferred_appointment_date must be today or later). Gather and confirm fields in chat before calling submit_vetted_practice_appointment or initiate_service_booking.

Slot no longer available

Service slots can be taken between get_service_availability and initiate_service_booking. Re-fetch availability and offer the user another time.

Endpoint

HTTP URL

https://orabiologics.com/mcp/ora

Transport

POST JSON-RPC 2.0 (MCP over HTTP with SSE)

Rate limit

120 requests per minute per client

Server name

OraBiologics

Version

2.0.0

Authentication

Request an MCP API key from your OraBiologics administrator. Keys use the format zyrook_<uuid>. Send the key on every request using either header:

Authorization: Bearer zyrook_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# or
X-MCP-API-Key: zyrook_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Prompts

Load a prompt at the start of a session to give your agent a consistent, human-like concierge persona and workflow.

• concierge

  Warm concierge persona for natural, human-like assistance.

• book_appointment

  Guided vetted practice appointment conversation.

Tools

Concierge tools are listed first. Catalog tools support programmatic access. Write tools create real submissions — confirm with the user first.

Content cards & presentation

Resources

• ora://concierge/guide

  Interaction guide: tools, UI apps, and conversational patterns.

• ui://concierge/chat

  Interactive MCP UI chat surface.

• ui://concierge/appointment-form

  Interactive appointment request form.

• ora://catalog

  Static JSON catalog of exposed models.

• ora://data/{model}/{id}

  Single serialized record by model key and id.

Examples

Load the concierge prompt

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/get",
  "params": {
    "name": "concierge",
    "arguments": {}
  }
}

Rich content card (with image)

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_content_card",
    "arguments": {
      "model": "service",
      "slug": "example-service-slug"
    }
  }
}

Book a service slot

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_service_availability",
    "arguments": {
      "service_slug": "example-service-slug"
    }
  }
}

// Then initiate_service_booking with date, time, and customer fields.
// Response includes checkout_url for payment.

Request a vetted practice appointment

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "submit_vetted_practice_appointment",
    "arguments": {
      "vetted_provider_slug": "example-practice-slug",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "preferred_appointment_date": "2026-06-15"
    }
  }
}

List journal posts (catalog)

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "list_records",
    "arguments": {
      "model": "post",
      "page": 1,
      "per_page": 10
    }
  }
}

Recommended concierge workflow

1. Load concierge prompt or read ora://concierge/guide.
2. Browse with get_content_card or search_records — show images and suggested replies.
3. For actions, call list_interactive_actions, collect missing fields in chat, confirm, then submit.
4. For services: get_service_availability → initiate_service_booking → share checkout_url.
5. Use catalog tools when you need paginated or raw JSON instead of chat cards.

Related discovery files