Skip to main content

Message Handling System (MHS) Adaptor

Learn about the Message Handling System and how to install, configure and integrate this adaptor into your own environment


Message Handling System is a pre-assured adaptor that makes it easier to connect to the NHS Spine and perform business operations.

The MHS adaptor is composed of three main services:

  • Outbound - Responsible for submitting requests to NHS Spine
  • Inbound - Responsible for listening for incoming requests from NHS Spine
  • Spine Route Lookup - Used to lookup routing and reliability information from Spine's directory service

Adaptor status and version

The current status for the MHS Adaptor is in production, beta.

We are currently in 'production beta', working with a limited number of partners to gain feedback and improve the service.

The latest version of the adaptor is: v1.3.1


This adaptor exposes a RESTful API that conforms to the HL7 Version 3 standard

Under the covers, the adaptor talks to the National Spine Service via Spine Directory Services and the Spine's own MHS.

This adaptor is a self-hosted component - you must deploy it within your own environment.

The following diagram illustrates the adaptor:

Diagram of three main services, Outbound, Inbound and Spine Route Lookup


You can deploy the MHS solution where you like, for example in a public or private cloud environment.

To demonstrate what we think makes a secure, scalable, and available deployment, we have created two examples of cloud environment, based on AWS and Azure.

We have used Terraform for automated deployment.

For more details, see MHS Adaptor github repository.  

A Docker image for each MHS service can be found within Docker Hub along with the install guidelines:


Test environments

In order to perform end-to-end testing of the MHS Adaptor, you will require access to an NHS Digital test environment.

The MHS adaptor connects to the following two test endpoints which are available in an NHS Digital test environment:

  • Spine Core Mocked endpoint - which you will use to send and receive messages
  • SDS mocked directory - which is used to lookup routing and reliability information

NHS Digital provides several environments to test these adaptors against:

  • OpenTest is an environment which can be used to perform initial test activities such as proof of concepts where an Health & Social Care Network (HSCN) connection is not available.
  • All other integration test activities are to be performed within a Path To Live environment. These activities include Development, Integration, Deployment and Non-functional tests.

To set up and configure OpenTest use Set up NHS Digital OpenTest connection.

To set up and configure Path to Live connectivity, see Path to Live environments.

Integration testing

The MHS Adaptor GitHub repository contains information on how to perform Integration Testing.

Contents include:

  • Prerequisites for integration testing
  • How to run local integration testing
  • Starting and testing the adaptor as docker containers
  • Running integration tests against mock components  


Each adaptor enables access to national NHS Systems.

The adaptor will need to be configured to integrate with the relevant NHS environments.

To do this you will need to register your adaptor through the standard NHS onboarding process. 

Operating/administration considerations

Find out how to operate the MHS adaptor in your own infrastructure in our github repository.  This covers areas such as log consumption, tooling, audit plus many other useful topics.


The MHS adaptors outbound service listens for requests from the GP system and transmits them to Spine.

The adaptor presents a simple HTTP synchronous interface which is used to make requests to Spine via the Outbound API.

For details of the endpoints exposed by this adaptor, see the MHS adaptor API specification. This is an Open API Specification (OAS) file.

To see how these endpoints fit within an end-to-end process flow, see our sequence diagrams.

Additional guidance

The National Integration Adaptors HIPPO team provide a support mailbox to support new market entrants integrating with this adaptor. To raise a support ticket please contact [email protected].

Last edited: 19 February 2024 1:06 pm