advancedmd-connector

advancedmd-connector is the one process in the organization that talks to AdvancedMD. Every consumer of AdvancedMD data — backend workflows (appointment-validator, srt-auths, note-audit, patient-intake), the admin-console credential check, and AI agents (Adam and any Claude Code, Cursor, or Desktop agent) — sends it a tool call over HTTP or MCP and gets back a JSON result. It holds the only AdvancedMD credentials, the only login session, and the only rate clock.

Today fifteen processes each hold AdvancedMD credentials, log in independently, and rate-limit independently against AdvancedMD's per-office-key caps (which bill $0.01 per excess call and refuse logins faster than about once a minute). The connector fixes that by owning the session and the clock centrally: one process, one rate clock, one tool surface, unchanged tool names and result shapes for every existing consumer. See SPEC.md for the full contract and docs/CONNECTOR_DECISIONS.md for why each choice was made.

Architecture

 backend workflows ------ JSON tool call ------> +-----------------------------+
 (validator, srt-auths,                          |    advancedmd-connector     |
  note-audit, intake,                            |                             |
  admin-console, chatbot)                        |  HTTP API   MCP surface     |
                                                  |      \        /             |
 agents ----------------- MCP tool call -------> |     receivers (one per      |
 (Adam via remote MCP;                           |       open request)         |
  Cursor, Claude Code,                           |          |                  |
  Desktop via stdio shim                         |     entry queue             |
  or remote MCP)                                 |          |                  |
                                                  |     worker loop  (1 at a    |
                                                  |          |        time)     |
                                                  |      handler                |
                                                  |          |                  |
                                                  |    request queue            |
                                                  |          |                  |
                                                  |     sender loop  (clock,    |
                                                  |          |        session)  |
                                                  +----------|------------------+
                                                             |  XML over HTTPS
                                                             v
                                                        AdvancedMD

One process. One port (default 8820). Everything above the dashed box is a consumer; nothing outside the box holds AMD credentials or sends XML.

Run locally in five commands

cp .env.example .env                      # fill AMD_USERNAME, AMD_PASSWORD, AMD_OFFICE_KEY
pip install -e ".[dev]"
export $(cat .env | grep -v '^#' | xargs) CONNECTOR_TOKENS_PATH=/tmp/tokens.json
connector tokens add myapp --priority interactive --tools '*'   # prints a token once
uvicorn --factory connector.app:build_app --host 0.0.0.0 --port 8820

GET http://localhost:8820/health should answer {"status": "starting"} or "ok" once the first login attempt completes. docker compose up --build runs the same thing containerized, reading the same .env.

Attach an agent

Tool names, argument schemas, and redacted result shapes are identical across all three attachment methods (SPEC 12.1), so an agent config can move from one to another without changing prompts.

Remote MCP (hosted agents, e.g. Adam) — point at the connector's streamable-HTTP surface directly:

{"mcpServers": {"amd-patients": {"type": "http",
  "url": "http://advancedmd-connector:8820/mcp/patients",
  "headers": {"Authorization": "Bearer <agent token>"}}}}

Ten routes are served: /mcp/patients, /mcp/visits, /mcp/providers, /mcp/codes, /mcp/billing, /mcp/payments, /mcp/masterfiles, /mcp/system, /mcp/ehr, and /mcp/all (the union).

Local stdio shim (agents on a workstation) — install the published advancedmd-mcp package and point it at the connector over the network; it holds no credentials and no tool logic:

{"mcpServers": {"amd-patients": {"command": "uvx",
  "args": ["advancedmd-mcp", "--domain", "patients"],
  "env": {"ADVANCEDMD_CONNECTOR_URL": "http://100.94.62.115:8820",
          "ADVANCEDMD_CONNECTOR_TOKEN": "<agent token>"}}}}

Claude Code plugin — plugin/ declares all nine stdio servers with ${ADVANCEDMD_CONNECTOR_URL} and ${ADVANCEDMD_CONNECTOR_TOKEN} environment references:

claude plugin add <path or repo>/plugin

The same plugin/.mcp.json is valid for Cursor and Claude Desktop by copy.

Use it from a workflow

Backend Python services use the SDK in orlando-derm-backend/lib/advancedmd_connector/, which keeps every existing method name and typed result:

from lib.advancedmd_connector import AmdConnector

connector = AmdConnector.from_env()          # ADVANCEDMD_CONNECTOR_URL, ADVANCEDMD_CONNECTOR_TOKEN
bundle = await connector.get_patient_bundle(patient_id)
result = await connector.tool("getdemographic", patient_id=patient_id)   # generic call

The SDK holds no AMD credentials, no XML, and no AMD URL — it is HTTP only. See SPEC 13 for the full method table and exception mapping.

Issue a token

Tokens are issued and revoked with the bundled connector CLI against the token table file (CONNECTOR_TOKENS_PATH):

connector tokens add appointment-validator --priority batch --tools '*'
connector tokens add my-agent --priority interactive --tools getdemographic,lookuppatient
connector tokens list
connector tokens revoke my-agent

A plaintext token is printed once at issuance and never stored or recoverable. See docs/OPERATIONS.md for the full flag reference and docs/TOKENS.md for the token model.

Where to look when something is slow

• GET /health (no token, internal network only) — session state, entry-queue depth and oldest wait, request-queue depth, and the rate clock's used/limit per tier, all in one call.
• GET /metrics (no token) — Prometheus text: tool call counts and wait histograms by caller/tool/outcome, AMD request counts and post-time histograms by tier, clock used/limit/sleep-time per tier, relogin and login-refusal counters, queue depths. See SPEC 18 for the full metric list and the alert conditions in SPEC 18.2.
• A slow AMD reply must never delay /health — the sender loop and /health run on the same event loop but blocking I/O is forbidden (SPEC 4.4), so a hung AMD call shows up as clock/queue pressure on /health, not as an unresponsive connector.

Batch schedule

The connector itself runs no batch jobs; it serializes whatever its batch-priority callers send. The consumers currently scheduled against it (SPEC 22 migration table) are appointment-validator (one nightly run), srt-auths (scan and event runs), and note-audit (one daily run). Batch-priority requests age into promotion after BATCH_AGING_MS (default 60 s) so a long batch backlog cannot starve interactive calls indefinitely (SPEC 5.3); deploys should still avoid these windows since a restart drops the in-memory session (SPEC 16.3).

Further reading

• SPEC.md — the full build contract.
• docs/CONNECTOR_DECISIONS.md — why each choice was made.
• docs/API.md — the HTTP API, mirrored from SPEC 11.
• docs/OPERATIONS.md — tokens CLI, deploy, rollback, alerts, and the fixture procedure.
• docs/TOOL_TO_XML_MAP.md — per-tool AMD request map and verification ledger.