Skip to main content

Model Context Protocol (MCP)

The Model Context Protocol (MCP) enables direct conversational access to the Air Doctor platform. The protocol offers a compact set of tools that enables partners to control each step of the interaction without UI embedding or REST calls. An LLM interprets user intent and selects actions from server-defined options. Under the HATEOAS principle, the server directs each step by sending action identifiers and schemas. MCP provides a predictable path and lowers integration complexity.

Workflow Overview​

Workflow Diagram
User → LLM → start → actions
                 ↓
             explain → schema
                 ↓
             perform → result / next actions
                 ↓
            login (when required)
                 ↓
                start

A typical MCP client follows this sequence:

  1. Start – Start a session and receive the current user state and the complete list of available actions.
  2. Explain – For each possible action, request an explanation that defines the action and the required arguments.
  3. Perform – When the user selects an action, call the perform tool with the action identifier and the arguments from explain.
  4. Login – If the server signals an authentication requirement, start the login flow.

This cycle continues as the conversation advances. If any step fails to identify an action or if the context shifts, such as after a successful login, call start again.

Tools Summary​

start​

This entry point returns the current user state and the set of available actions. The server may instruct you to invoke a new start call when the user’s status changes or after critical errors. Use the returned information to present options to the user.

explain​

explain accepts an action_id from a previous response and returns a structured description of the action. The response includes:

  • A designation - The internal function name that the serve invokes.
  • A group - A textual description of the action category.
  • A description - A human‑readable explanation of the action.
  • A schema - A JSON Schema that defines the arguments for the action.
important

Never guess identifiers or parameters. Call explain before perform and follow the schema without deviation.

note

If the server rejects the identifier in either explain or perform, call start again.

Treat the LLM as a controlled GUI: you describe the screen and the user’s request, then select the correct action. Some actions may present a confirmation screen or additional steps before they execute.

perform​

The perform tool executes an action that explain defines. Provide the same action_id and the full set of schema arguments. The response appears as a JSON object. The structure depends on the action. It may:

  • Provide requested data, such as search results.
  • Present a new "screen" that lists the next step and the available follow-up actions.
  • Complete the action directly, such as booking an appointment.
caution

Some actions remove data or confirm an appointment. Ensure that the user understands each consequence before you trigger perform.

login​

Use this tool only when the server instructs you to use it. The tool accepts no input and returns an HTTP 401 response to signal an authentication requirement.

Use login to start the login flow when the user must authenticate or re-authenticate. After the user completes login, call start again to refresh the session state. If you rely on your own OAuth flow, you may start authentication without this tool. The tool only signals that the operation requires explicit user consent.

Authentication and Tokens​

Air Doctor endpoints support OAuth 2.1. Dynamic client registration is not active, but clients can be added on request. When a partner externalizes user management, the partner may preemptively send an access token, such as a session-token cookie, X-Token header, with each MCP calls. Refresh tokens when they expire. Follow the rules in the Access Token Handling section.

Summary​

MCP provides a precise and controlled structure for conversational integration with the Air Doctor platform. The HATEOAS-style path uses start to show available actions, explain to define each option, perform to carry out the selected option, and login when authentication is necessary.

This method supports medical assistance workflows in a guided dialogue format. It fits partners who want a chat-style experience with strict control and server-driven orchestration.