Docs / MCP

The MCP interface.

neolife speaks MCP. Your agents can draft an order, attach the data, and submit it — then read the status as it fills and ships. Every call runs through the same rail a person does, and a licensed provider approves every order. Always.

Book a demo Back to Agents

Overview

Draft, attach, submit, read. A human still approves.

neolife exposes its ordering rail over the Model Context Protocol. An agent connects and gets a small, honest tool set: build an order, attach the supporting data, submit it for review, and read the status back. The same rules that govern a person clicking through the dashboard govern an agent calling a tool.

There is no tool to skip the provider, because that path doesn't exist. Agents do the assembly; a licensed provider makes the decision. Compounded medications are prepared by a licensed compounding pharmacy and are not FDA-approved products.

POST /mcp/tools/call

Authentication

Signed requests, per-agent identity.

Every request travels over TLS and carries two things: an API key that identifies your integration, and an HMAC-SHA256 signature over the request body computed with your signing secret. neolife recomputes the signature on receipt; a mismatch is rejected before the call runs.

API key

Sent as Authorization: Bearer. Identifies the integration and the clinic behind it.

HMAC signature

An X-Neolife-Signature header — HMAC-SHA256 of the raw body, so tampering fails the check.

Per-agent identity

Each agent gets its own token, so the audit log names the exact agent behind every call.

Tokens are scoped. A read-only token can call orders.status but not orders.submit. Scope requests are denied with a 403, never silently downgraded. Rotate a token from the dashboard at any time; a rotated key stops working immediately.

Authorization: Bearer nl_live_a1b2c3…
X-Neolife-Signature: sha256=<hmac-of-raw-body>
X-Neolife-Agent: agt_scheduler_01
Content-Type: application/json

Illustrative headers. Your real keys and signing secret live in the dashboard — neolife never displays a secret twice.

Tools

Four verbs. The order does the rest.

Every tool is called through POST /mcp/tools/call with a tool name and an arguments object.

orders.drafttool

Assemble line items, sig, and shipping into a draft order. Nothing reaches the pharmacy — the draft sits in the queue.

Parameters

clinic_idstring: The clinic placing the order.
patient_refstring: Opaque patient reference. No raw PHI is passed over MCP.
itemsarray<{ sku, qty, sig }>: Line items. sku is the formulary code, qty an integer, sig the dosing instruction.
shipping{ method, to }: Shipping method (standard, expedited, cold_chain) and an address reference.

Returns

The draft order object with status "draft". No provider has seen it yet; it is fully editable.

orders.attachtool

Attach intake answers, labs, or connected-device readings to a draft so the reviewing provider sees the full picture.

Parameters

order_idstring: The draft to attach to.
kindstring: One of intake, lab, device, note — the type of evidence being attached.
payload_refstring: Reference to the stored document or reading. Content is held in neolife, not passed inline.

Returns

The updated draft with the attachment recorded. Attaching data may raise an amber flag for the provider.

orders.submittool

Route a draft to a licensed provider for approval. The order does not reach the pharmacy until a human approves it.

Parameters

order_idstring: The draft to submit.
idempotency_keystring: Optional. A client-supplied key so a retried submit doesn't create a duplicate.

Returns

The order object with status "awaiting_provider_approval" and approval_required: true. This is a hard stop for the agent.

orders.statustool

Read the current state of an order, or subscribe for changes — approved, filled, shipped, tracking number — pushed straight back to your agent.

Parameters

order_idstring: The order to read.
subscribeboolean: Optional. When true, state changes are pushed to your registered webhook as they happen.

Returns

The order object with its current status, any flags, and — once shipped — the carrier and tracking number.

The order object

One shape, from draft to doorstep.

Every tool returns the same order object. Its status moves forward as the order is approved, filled, and shipped — the fields never change shape.

{
  "order_id": "ord_19d4",
  "status": "awaiting_provider_approval",
  "approval_required": true,
  "flags": [],
  "compounded_by": "licensed compounding pharmacy"
}

order_idstring: Stable identifier for the order. Use it with orders.attach, orders.submit, and orders.status.
statusstring: Lifecycle state: draft → awaiting_provider_approval → approved → filled → shipped. An order can also be declined.
approval_requiredboolean: Always true for agent-placed orders. There is no path that sets this to false.
flagsarray<string>: Amber review flags — dose limits, interaction risk, unusual quantities. Agents can read them; only a provider can clear them.
compounded_bystring: Who fills the order. Compounded medications are prepared by a licensed compounding pharmacy and are not FDA-approved products.

Guardrails

The rules live in the rail, not the UI.

Approval, flags, and audit don't change because the order came from an agent. They aren't settings you can turn off.

Approval is non-bypassable

No tool, no token, no scope lets an agent skip the provider. An agent-placed order stops at awaiting_provider_approval until a licensed provider taps approve.

Amber flags surface

Dose limits, interaction risk, and odd quantities raise an amber flag on the order for the provider to see. Agents can read flags; they can't clear them.

Every call is logged

Each call is recorded with the tool, the arguments, the timestamp, and the identity behind the token. The audit trail reads the same whether a human or an agent placed the order.

Errors

Errors say what went wrong.

Failures return a standard HTTP status and a machine-readable code. Retrying a 422 or 409 without changing the request will fail the same way.

Status	Code	Meaning
`401`	`unauthorized`	Missing, expired, or badly signed request. Check the API key and the HMAC signature.
`403`	`scope`	The token is valid but lacks the scope for this tool — e.g. a read-only token calling orders.submit.
`422`	`validation`	The arguments didn't validate — a missing sig, an unknown sku, or a malformed shipping block.
`409`	`conflict`	The order isn't in a state that allows this call — e.g. attaching to an already-submitted order.

Wire your agents into the rail.

Connect over MCP, draft real orders, and watch a licensed provider approve each one. See it run, or head back to the overview.

Book a demo Back to Agents