Technical note: Ordina's MCP servers

How Ordina's two Model Context Protocol servers work, their endpoints, authentication, tools, and how to connect a client or build on them.

Ordina speaks the Model Context Protocol (MCP), the open standard AI assistants use to call tools. There are two servers: a public one for customers' assistants and a private one for business owners.

  1. ClientClaude, ChatGPT or your own agent.
  2. MCP over HTTPJSON-RPC 2.0 with POST.
  3. OrdinaTools run against live data.
  4. The businessBookings and orders land in the dashboard.

The two servers

Customer server Owner server
Endpoint https://www.useordina.com/api/mcp https://www.useordina.com/api/mcp/owner
Who uses it Any assistant acting for a customer The business owner's own assistant
Auth None OAuth 2.1 bearer token
Scope Public directory, one business at a time by handle The owner's own business only, from the token
Plan Works for every listed business Owner on the Business plan; checked on every request

Transport

Both use MCP's Streamable HTTP transport, stateless: send one JSON-RPC 2.0 message or a batch with POST and get JSON back. GET answers 405 because the servers never open a server-to-client stream. Supported protocol versions: 2025-06-18, 2025-03-26 and 2024-11-05. CORS is open, so browser-based clients work.

POST https://www.useordina.com/api/mcp
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"get_business","arguments":{"handle":"ordina"}}}

Customer tools

Tool What it does
search_businesses Search the public directory by name, service or city; returns handles
get_business Details, hours, services with prices, policies, products, and which services can be booked directly
check_availability Real open times for one service over the next two weeks, in the business's timezone
book_appointment Books a service, in two steps confirmed by a code the customer receives; needs the customer's name and phone with country code
place_order Orders products, in two steps confirmed by a code the customer receives
get_store_checkout_link For a WooCommerce store, a link to its checkout with items in the cart; for a Shopify store, each product's page on the store's own website
get_booking_link The business's booking page
check_order_status Status of an order

Bookings from assistants are marked AI assistant in the business's Messages. Calls are rate limited per IP, with a tighter limit on real bookings.

Bookings and orders: the one-time code

The customer server has no sign-in, so a name, phone and email passed to it prove nothing on their own. book_appointment and place_order therefore take two calls:

  1. The first call runs every check, holds the time (or reserves the items) for 15 minutes, and sends a 6-digit code to the customer's email, or to their phone by text message when no email is given. Nothing is booked or ordered and the business is told nothing. The result has verification_required: true, a verification_id, sent_to (masked, for example a***@gmail.com or +234 *** *** 4521), expires_in_seconds and next. It never contains the code.
  2. The second call repeats exactly the same details and adds verification_id and verification_code, the code the customer read and typed back. A right code commits exactly what was held: the booking with its confirmation and the owner's alert, or the order (a pay-later order is placed; one paid up front returns its payment link).
{"name":"book_appointment","arguments":{"handle":"ordina","service_id":11,"date":"2026-11-06",
 "time":"10:00","customer_name":"Maya Brooks","customer_phone":"+14155550123",
 "customer_email":"maya@example.com","customer_confirmation":"yes, book it",
 "verification_id":"3f0c...","verification_code":"123456"}}

The rules:

  • A code works once, for 10 minutes, with at most 5 tries. A wrong, expired or used code commits nothing; after 5 wrong tries the hold is let go.
  • The details must be the same as in the first call. Different details are refused, and a new first call sends a new code for them.
  • resend_code: true with the verification_id sends the code again, once, at least 30 seconds after it was sent.
  • One email address or phone number gets at most 3 codes an hour and 6 a day across every business, with further limits per business and per connection. Phone codes go only to numbers in the markets Ordina serves, and never to a number that replied STOP.
  • dry_run: true checks everything and sends no code.

Owner server: authentication

The owner server follows the MCP authorization spec, so clients like Claude connect with no configuration beyond the URL:

  1. A request without a token gets 401 with a WWW-Authenticate header pointing to the protected-resource metadata (RFC 9728) at /.well-known/oauth-protected-resource.
  2. The client reads the authorization-server metadata at /.well-known/oauth-authorization-server.
  3. It registers itself with dynamic client registration (RFC 7591) at /api/oauth/register.
  4. It sends the owner to /oauth/authorize with PKCE (S256), which is required. The owner signs in and approves; scope is business.
  5. It exchanges the code at /api/oauth/token (authorization_code), and later refreshes with refresh_token. Tokens can be revoked at /api/oauth/revoke.
  6. Every call carries Authorization: Bearer and the access token. The business comes from the token alone.

The plan and account are checked on every request, so a lapsed or suspended business stops working at once. Owners can see and revoke connections under Integration, AI assistants, Connected.

Owner tools

They are the same tools the dashboard Secretary uses, bound to the owner's business: get_my_business, list_appointments, list_orders, list_payments, get_revenue, rank_customers, get_customer_summary, get_customer_insight, list_services, list_categories, update_service, hide_service, unhide_service, add_service, delete_service, create_category, update_faq, draft_email, invite_team_member, update_appointment_status, reschedule_appointment, cancel_appointment, mark_no_show, update_order_status, cancel_order, block_time, list_blocked_time, unblock_time, list_team, and photo tools (list_service_photos, add_service_photo, get_photo_upload_link, remove_service_photo).

Irreversible actions are confirmed in code, not in the prompt. Adding or deleting an item, emailing someone and inviting staff return a proposal instead of acting. Nothing happens until the client calls confirm_action with that proposal after the owner says yes.

Implementing a client

  • Claude: Settings, Connectors, Add custom connector, and the URL above. The OAuth flow runs by itself.
  • Your own agent: use any MCP client library with the Streamable HTTP transport. For the owner server, implement the OAuth flow above, or use a library that does. Call initialize, then tools/list to read the current tool schemas; do not hard-code them, they grow.
  • Customer server only? No auth: POST JSON-RPC and go. Start with search_businesses or get_business with a known handle.

For plain REST access to your own data without MCP, see API keys.

Did this answer it?If not, write to help@useordina.com with your handle, or contact us. A person replies.
Contact us