MedEx API + MCP

An API and Model Context Protocol (MCP) server for Bangladesh medicine information.

Important — data source: This project ships with a synthetic fixture provider by default. It does not serve live MedEx data. No official or licensed MedEx API was available, and no written authorization to scrape or redistribute MedEx's database exists. Every default record is marked source.kind: "fixture" and must never be used for clinical decisions. See DATA_SOURCES.md for the full authorization status and how to plug in an authorized live provider.

What it does

• Exposes medicine, generic, manufacturer, and category information over a versioned REST API (/api/v1).

• Exposes the same capabilities as MCP tools so AI agents (including Hermes Agent) can query the data with structured, validated inputs.

• Ships with everything wired to a local fixture dataset so it runs offline with zero credentials — ideal for development, testing, and demos.

Related MCP server: GitHits

Architecture

                 ┌────────────────────┐
   REST clients ─▶                    │
                 │   Express API      │──┐
   AI agents ───▶   (src/api)         │  │   Provider interface
     (MCP)       │                    │  │   (src/provider/provider.ts)
                 └────────────────────┘  │
                 ┌────────────────────┐  │        ▲
   MCP client ──▶│   MCP server       │──┘        │
     (stdio)     │   (src/mcp)        │     FixtureProvider (default)
                 └────────────────────┘     (src/provider/fixture-provider.ts)
                                              ▲ reads
                                        fixtures/medex-fixtures.json

Two entry points share one Provider interface:

• REST API (src/api) — Express app with validation, rate limiting, security headers, and consistent error envelopes.

• MCP server (src/mcp) — MCP SDK server exposing the provider as tools over stdio.

Provider-specific data access is kept behind the Provider interface, so the routes and MCP tools never touch the data source directly. Swapping in an authorized live provider means adding one implementation and selecting it via MEDEX_PROVIDER — no route or tool changes.

Implemented API endpoints

Full request/response schemas: openapi.yaml · prose docs: API.md.

Implemented MCP tools

Connection details for agents: MCP.md.

Installation

Requires Node.js ≥ 20 (developed and tested on Node 26).

git clone https://github.com/shoaibsanto/medex-api-mcp.git
cd medex-api-mcp
npm install
npm run build

Local development

# Start the REST API on http://127.0.0.1:3000
npm start

# Or run in watch mode during development
npm run dev

# Start the MCP server on stdio
npm run mcp

Configuration is read from environment variables (see .env.example):

Running tests

npm run typecheck   # TypeScript, no emit
npm test            # vitest: unit + API + MCP + validation + rate-limit
npm run build       # compile to dist/

The suite covers provider unit behaviour, REST integration (including 400/404 validation and error paths), MCP tool registration and structured output, API↔MCP data consistency, rate limiting, CORS, and security headers.

Connecting the MCP server to an AI agent

The MCP server speaks stdio. Add it to your agent's MCP config. For Hermes Agent, the relevant block is:

mcp_servers:
  medex:
    command: node
    args:
      - /absolute/path/to/medex-api-mcp/dist/mcp/index.js

The REST API is the default integration boundary for anything that prefers HTTP. See MCP.md for details and tool schemas.

Data-source authorization and limitations

• Default provider = synthetic fixtures. No live MedEx data is served or redistributed by this repository.

• MedEx has a privacy policy but no terms-of-service page, no official API, and no published licensing terms for automated collection or redistribution. Its robots.txt is permissive, but that governs crawling access — it is not a copyright or database license.

• The fixtures are fictional records (fictional brands, manufacturers, and prices) that exist solely to exercise the API and MCP code paths.

• To use real data you must obtain written authorization and an official or licensed feed, then implement a Provider and select it with MEDEX_PROVIDER=live. The live case currently throws deliberately rather than silently serving fixtures.

See DATA_SOURCES.md for the full write-up.

Security and responsible use

• No secrets are committed. Configuration uses .env (git-ignored) with placeholders in .env.example.

• The API sets security headers (helmet), enforces input validation, applies rate limiting, and returns consistent error envelopes without stack traces.

• This project is intended for informational, developer, and research use. Medicine information is not a substitute for professional medical advice. Never present fixture data as verified clinical information.

See SECURITY.md.

Project status

v0.1.0 — functional MVP.

• ✅ REST API implemented and tested

• ✅ MCP server implemented and tested (stdio)

• ✅ Synthetic fixture provider, extensible Provider seam

• ✅ OpenAPI spec, docs, CI workflow

• ⏳ Authorized live provider: not implemented (requires authorization)

See CHANGELOG.md.

License

Source code in this repository is released under the MIT License. This applies to the code only — not to any third-party medicine data. See DATA_SOURCES.md for why no upstream data is redistributed.