--- name: iblai-connect-epic description: "Read and write Epic data through the Epic on FHIR (FHIR R4, STU3, DSTU2) and open.epic interfaces and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Epic data, or to set up an Epic MCP connection on ibl.ai." metadata: kind: guide --- # Epic connector for AI agents > A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/epic — not part of the iblai/vibe repository. Checked against Epic's documentation on October 20, 2026; test it against your own Epic setup before you rely on it. Epic is an electronic health record system used by hospitals and health systems. It holds patient demographics, encounters, problems, allergies, medications, results, clinical notes, orders, appointments and coverage. ## Auth & conventions - **API:** Epic on FHIR (FHIR R4, STU3, DSTU2) and open.epic interfaces (FHIR R4). FHIR R4 REST APIs covering USCDI data and more: about 60 resource types in the sandbox, including Patient, Observation, Condition, MedicationRequest and DocumentReference, plus Bulk FHIR export on Group and CDS Hooks. - **Base URL:** https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4/ (sandbox); production base URLs are per organization, listed in the open.epic Endpoints directory - **Access:** Issued by your administrator. Anyone can create an app on fhir.epic.com and test it in the free sandbox. Production use needs the app marked ready for production and each Epic customer organization to download its client ID. - **Auth:** SMART on FHIR EHR launch (OAuth 2.0 authorization code); SMART standalone launch (OAuth 2.0 authorization code); SMART Backend Services (JWT). OAuth 2.0 with SMART on FHIR. Sandbox endpoints: https://fhir.epic.com/interconnect-fhir-oauth/oauth2/authorize and /oauth2/token. Backend apps use the client_credentials grant with a signed JWT client assertion. - Keep Epic credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file. - Destructive or outward-facing calls are marked **Confirm with the user first** — do. ## Reads - **Patients** — Patient read and search, plus the $match and $summary operations listed in the sandbox CapabilityStatement. - **Lab results and vitals** — Observation read and search; DiagnosticReport read and search. - **Problems and allergies** — Condition and AllergyIntolerance read and search. - **Medications** — MedicationRequest read and search. - **Clinical notes** — DocumentReference read and search for clinical notes and documents. - **Population exports** — FHIR Bulk Data Access: Group $export kickoff, status polling and file download. ## Writes - **Clinical notes** — DocumentReference create and update (Clinical Notes) files a note into the patient chart. **Confirm with the user first.** - **Observations** — Observation create and update, as listed in the sandbox CapabilityStatement. - **Problems and allergies** — Condition.Create and AllergyIntolerance.Create (Patient Chart). ## Expose it to an ibl.ai agent (MCP) Epic did not publish an MCP server of its own when this skill was checked. Host a small MCP server that wraps the calls above, then register it below. First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`): ```bash npx skills add iblai/vibe --all # then, in your coding agent: /iblai-api-login ``` Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`. 1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`. - Epic supports per-user OAuth: `auth_type=oauth2` with `auth_scope=user` and a linked `oauth_service` makes each person connect their own account in the chat. It needs an `auth_{provider}` credential in the organization's credential store first. 2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back. 3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged. Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill. ## Example prompts - "Pull this patient's active problem list and current medications from Epic." - "Show the last three hemoglobin A1c results for patient MRN 1234567." - "Draft a visit summary from today's encounter notes for my review." - "List allergies recorded for this patient and flag any added in the last year." ## Guardrails - Records are HIPAA protected health information (PHI). Access is limited to the scopes granted to the app and, in production, to organizations that have activated its client ID. - Request the narrowest Epic scopes or role the task needs, and prefer a read-only credential for agents that only answer questions. - Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request. - Before any write, show the user exactly what will change and wait for a yes. - Page through large result sets and back off on rate-limit responses instead of retrying in a loop. ## References - Epic on FHIR developer site: https://fhir.epic.com/ - Epic on FHIR OAuth 2.0 documentation: https://fhir.epic.com/Documentation?docId=oauth2 - open.epic FHIR interface catalog: https://open.epic.com/Interface/FHIR - This connector on ibl.ai: https://ibl.ai/developer/connectors/epic - ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections