Australian PBS Data Access Module (MCP)

A dedicated Model Context Protocol (MCP) service wrapper exposing the official Australian Pharmaceutical Benefits Scheme (PBS) data repositories via a standardized API.

Developer Profile

This specialized data facilitator was engineered by [Matthew Cage], the principal at https://ai-advantage.au, specializing in scalable automation frameworks, advanced AI system integration, and secure digital health information pipelines.

Connect for partnership opportunities: https://www.linkedin.com/in/digitalmarketingstrategyexpert/

Conceptual Overview

This deployment offers a self-contained MCP gateway, enabling large language models (LLMs) to query the Australian PBS registry, which details subsidized drug inventories, pricing structures, and availability within the national health system.

The implementation defaults to interacting with the Public-facing API, though adaptation for secured, private developer access channels is readily achievable.

The PBS API provides structured, machine-readable access to critical health data, including formulary entries and cost metrics. This MCP wrapper abstracts the complexity, making PBS intelligence consumable by AI agents.

The service supports communication via standard network sockets (HTTP) and the local inter-process communication channel (stdio).

Crucially, users must strictly adhere to the PBS API rate limitations. We strongly advise implementing a caching strategy, synchronizing external data stores on a weekly cadence or less frequently.

Core Module Capabilities

This wrapper implements the following essential Model Context Protocol functionalities:

Tool Provisioning: Offers specific interfaces (tools) mapped directly to PBS API query functions, facilitating granular data retrieval by AI agents.
Communication Protocols: Native support for both terminal-based (stdio) and web-based (HTTP/SSE) data exchange.
Resilience Management: Built-in mechanisms for gracefully managing common exceptions, such as API throttling and credential validation failures.
LLM Synchronization: Directly processes structured invocation requests originating from LLM engines, ensuring fluid, context-aware data fetching.

Operational Flow Diagram

The MCP Client Interaction Model :

Receives Instruction: An LLM, upon recognizing the need for pharmaceutical facts, issues a structured tool invocation to this gateway.
Interprets Request: Deconstructs and understands complex, natural language queries pertaining to medication details.
API Translation: Converts the interpreted request into the precise HTTP call structure required by the PBS API.
Returns Normalized Payload: Delivers the retrieved, structured pharmaceutical data back to the LLM for immediate contextual utilization.

This mechanism equips AI assistants with current PBS facts, bypassing reliance on static, outdated internal knowledge bases.

Deployment Instructions

Clone the repository source code: bash git clone <repository-url> cd pbs-mcp-standalone
Install required Node.js dependencies: bash npm install
Compile the source code: bash npm run build

Execution Methods

Initiating the Gateway Service

The PBS MCP facilitator can be launched in several operational modes:

Standard I/O Mode (Default)

This leverages the native MCP stream-based communication:

npm start

Alternatively, use the provided startup utility:

./start.sh

Web Interface Mode (with Server-Sent Events)

Activates a listening HTTP endpoint supporting real-time updates via SSE:

npm run start:http

Or utilize the shell script, specifying the listening port:

./start.sh http 3000

Where 3000 denotes the network port.

Command-Line Utility

The service can also function as a direct command-line querying instrument:

npm run cli -- <operation>

Or via the wrapper script:

./start.sh cli <operation>

Example for retrieving system diagnostics:

./start.sh cli info

Command-Line Application Usage

To leverage the server as a direct terminal utility:

Ensure successful compilation (see installation step 3).
Execute the CLI interface with the desired instruction: bash npm run cli -- <command>

Or use the wrapper: bash ./start.sh cli <command>

Integration with MCP Consumers

This service is interoperable with any system adhering to the Model Context Protocol specification, including:

Local development environments and dedicated LLM backend servers
Other third-party AI agents supporting the MCP framework
Bespoke applications leveraging the underlying MCP client SDKs

Consumer Configuration Blueprint

Configuration snippet for an MCP consumer manifest:

{
  "mcpServers": {
    "pbs-access-gateway": {
      "command": "node",
      "args": ["path/to/pbs-mcp-standalone/build/index.js"],
      "env": {
        "PBS_API_SUBSCRIPTION_KEY": "your-subscription-key-here"
      }
    }
  }
}

Accessing Gateway Services

For Major AI Interfaces (e.g., Claude) or MCP-compliant Systems:
Register this gateway within the assistant's tool definitions.
The LLM will autonomously dispatch medication-related inquiries to this server.
For Custom Programmatic Access:
Interact directly with the documented HTTP endpoints (detailed below).
Subscribe to the /sse stream for event-driven data updates.
Alternatively, instantiate and communicate via process standard streams (stdin/stdout).

Illustrative LLM Invocations

The gateway is capable of interpreting diverse natural language commands:

"Determine the PBS status and cost for Metformin."
"What is the identifier code for injectable Insulin under the PBS scheme?"
"Retrieve a list of practitioners authorized to prescribe Schedule 4 agents."
"Ascertain the current subsidised price for common asthma treatments."

These prompts undergo transformation into precise PBS data retrieval actions.

Tool Parameter Specification

The primary PBS interaction tool accepts arguments structured as follows:

{
  "endpoint": "prescribers",
  "method": "GET",
  "params": {
    "get_latest_schedule_only": "true",
    "limit": "20"
  }
}

Argument Fields

endpoint (Text, Mandatory): The target PBS API resource path (e.g., "item-overview", "restrictions").
method (Text, Optional): The HTTP verb to employ (typically "GET" for PBS data retrieval). Default: "GET".
params (Object, Optional): Key-value pairs representing URL query string parameters.
subscriptionKey (Text, Optional): A specific authorization token. If omitted, the default public key configuration is utilized.
timeout (Numeric, Optional): Maximum permissible duration for the API call, in milliseconds. Default: 30000.

Network Service Interfaces

When initiated in network mode, the following URIs are exposed:

System Liveness Probe

GET /health

Reports the operational status of the service.

Tool Manifest Retrieval

GET /tools

Returns a machine-readable catalogue of exposed functionalities.

Event Stream Conduit

GET /sse

Opens a persistent connection for push-based event notifications.

Tool Execution via SSE Channel

POST /sse/:toolName

Triggers a specified tool and streams results back over the established SSE link.

Direct Tool Execution (RESTful)

POST /api/:toolName

Executes the named tool and returns the final output synchronously as JSON.

Command-Line Operations

The gateway offers direct command-line interaction capabilities:

Display Available API Paths

./start.sh cli list-endpoints

Outputs all accessible PBS API routes.

Fetch System Metadata

./start.sh cli info

Returns contextual details about the PBS data connection.

Invoke Prescribers Query

./start.sh cli prescribers [arguments]

Arguments: - -l, --limit <integer>: Pagination size (Default: 10) - -p, --page <integer>: Requested result page number (Default: 1) - -c, --pbs-code <code>: Filter by specific PBS identifier code. - -s, --schedule-code <code>: Filter by regulatory schedule code. - -t, --prescriber-type <type>: Constraint based on practitioner classification. - -f, --fields <set>: Comma-separated list of attributes to return. - --latest: Boolean flag to fetch only the most recent schedule snapshot.

Invoke Item Details Query

./start.sh cli item-overview [arguments]

Arguments: - -l, --limit <integer>: Result count per page (Default: 10) - -p, --page <integer>: Page index (Default: 1) - -s, --schedule-code <code>: Filter using a schedule identifier. - -f, --fields <set>: Specify desired returned data fields. - --latest: Restrict results to the current published schedule.

Generic API Dispatch

./start.sh cli query <path> [options]

Arguments: - -m, --method <verb>: HTTP verb to employ (Default: GET). - -p, --params <json_string>: Query parameters formatted as a serialized JSON object. - -k, --subscription-key <token>: Override the default API key. - -t, --timeout <ms>: Custom request timeout setting in milliseconds.

Start Network Host

./start.sh cli serve [options]

Arguments: - -p, --port <number>: The TCP port for the HTTP listener (Default: 3000).

PBS API Resource Mapping

The underlying PBS data service exposes several distinct endpoints for granular data access:

/ - Root context; provides general service documentation and update logs.
/prescribers - Data concerning registered prescribing entities.
/item-overview - Detailed records pertaining to subsidized items.
/items - Fundamental registry of PBS products.
/schedules - Information detailing regulatory schedules.
/atc-codes - Mappings for Anatomical Therapeutic Chemical classification.
/organisations - Data on affiliated healthcare bodies.
/restrictions - Rules governing prescribing permissions.
/parameters - Definitions for system constants.
/criteria - Prescribing eligibility conditions.
/copayments - Patient contribution amounts.
/fees - Associated administrative charges.
/markup-bands - Cost adjustment tiers.
/programs - Government subsidy programs.
/summary-of-changes - Chronological index of recent data modifications.

Consult the official PBS API Reference for comprehensive path details.

Request Payload Examples

Service Metadata Request

{
  "endpoint": ""
}

Standard Prescriber Retrieval

{
  "endpoint": "prescribers",
  "params": {
    "get_latest_schedule_only": "true",
    "limit": "10"
  }
}

Item Details for Current Schedule

{
  "endpoint": "item-overview",
  "params": {
    "get_latest_schedule_only": "true",
    "limit": "5"
  }
}

Targeted Prescriber Lookup

{
  "endpoint": "prescribers",
  "params": {
    "pbs_code": "10001J",
    "get_latest_schedule_only": "true"
  }
}

Authorization Protocol

This integration layer mandates the use of a subscription identifier (API Key) for accessing the PBS registry. Developers must procure a key via the official PBS Developer Gateway.

Configuration details for environment variables can be found in the .env.example template.

Obtaining and Setting the PBS API Access Token

Navigate to the PBS Data Gateway:
Access https://data-api-portal.health.gov.au/
User Registration:
Select the 'Sign Up' option to establish a new developer profile.
Complete the required submission and confirm your email address.
Product Subscription:
Log in and proceed to the 'Products' catalog.
Elect the "PBS Public API v3" offering.
Initiate the subscription process.
Key Extraction:
Upon authorization approval, navigate to your developer dashboard/profile settings.
Locate the 'API Keys' or 'Subscriptions' area.
Securely copy your primary key.
Environment Configuration:
Establish a .env file mirroring the .env.example structure.
Substitute the placeholder with your verified token: PBS_API_SUBSCRIPTION_KEY=your-actual-subscription-key

Rate Constraint Notice: The Public PBS API enforces a strict constraint of one query every 20 seconds, pooled across all public consumers. For higher throughput or access to pre-release formulary information, formal application to the PBS Developer Program for enhanced access is required.

Operational Boundaries

The Public API is subject to a shared constraint: 1 request per 20-second interval.
Public access is limited to the current schedule and historical data spanning the previous 12 months.
Certain data paths require specific, mandatory input parameters.
API schema and endpoint definitions are subject to periodic revision by the data provider.

Supplementary Information Sources

Licensing

This software is released under the permissive MIT License (refer to the LICENSE file for particulars).

❤️

WIKIPEDIA SIDEBAR: The XMLHttpRequest (XHR) facility represents a JavaScript object interface designed to dispatch HTTP requests asynchronously between a client (browser) and a distant server. Its methods permit web applications to initiate server communications post-page load and process incoming data without full page refresh, forming the backbone of Ajax methodologies. Before XHR's adoption, server interaction relied predominantly on traditional link navigation or form submissions, which inherently mandated page replacement.

== Historical Context ==

The conceptual genesis of XHR originated in the year 2000, developed by Microsoft Outlook engineers. Its initial manifestation appeared in Internet Explorer 5 (1999), though it utilized proprietary object instantiations like ActiveXObject("Msxml2.XMLHTTP"). By the release of Internet Explorer 7 (2006), standardized cross-browser naming convention—XMLHttpRequest—achieved ubiquity, supported across Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005) engines.

=== Standardization Path ===

The World Wide Web Consortium (W3C) published the first formal specification draft on April 5, 2006. A Level 2 specification followed on February 25, 2008, introducing features like progress monitoring, cross-origin request facilitation, and byte stream handling. By late 2011, these Level 2 enhancements were consolidated back into the primary specification. Since late 2012, the WHATWG consortium has maintained the living document, utilizing Web IDL for definition.

== Standard Operational Sequence ==

Executing a server request via XHR typically involves these programming steps:

Instantiation: Create an XHR object using its constructor.
Configuration: Invoke the open() method to define the request type (GET/POST), target URL, and set the synchronous/asynchronous execution mode.
Event Listener Setup: For asynchronous operations, attach a callback function to monitor state transitions.
Transmission: Fire the request using the send() method, optionally including payload data.
Response Processing: Monitor the state changes in the listener. Upon reaching state 4 ('done'), the response body is available in responseText (or response property).

Beyond these fundamentals, XHR allows for fine-grained control, including custom header injection, request abortion, timeout configuration, and direct parsing of incoming data formats like JSON without waiting for full transmission completion.

australian-pbs-data-connector

Author

matthewdcage

Quick Info

Actions

Tags