---
name: iblai-connect-athenahealth
description: "Read and write athenahealth data through the athenaOne APIs (proprietary) and athenahealth FHIR APIs (R4, DSTU2) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with athenahealth data, or to set up an athenahealth MCP connection on ibl.ai."
metadata:
  kind: guide
---

# athenahealth connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/athenahealth — not part of the iblai/vibe repository. Checked against athenahealth's documentation on October 20, 2026; test it against your own athenahealth setup before you rely on it.

athenaOne is athenahealth's cloud EHR, practice management and billing service. It holds practices, departments, providers, patients, appointments, clinical charts and documents, and claims and financial data.

## Auth & conventions

- **API:** athenaOne APIs (proprietary) and athenahealth FHIR APIs (R4, DSTU2) (Mixed). Proprietary athenaOne REST APIs with read and write across administrative, clinical and financial workflows, keyed by practice ID; FHIR R4 APIs for USCDI data; changed-data subscription feeds and event notifications.
- **Base URL:** https://api.platform.athenahealth.com/v1/{practiceid}/ (Production) and https://api.preview.platform.athenahealth.com/v1/{practiceid}/ (Preview); FHIR R4 global base: https://api.platform.athenahealth.com/fhir/r4
- **Access:** Partner or license program. Anyone can register on the Developer Portal; Preview credentials reach a public sandbox. Certified FHIR APIs are free. athenaOne and non-certified APIs need Platform Services or the Marketplace Partner Program, and each practice must enable the app.
- **Auth:** OAuth 2.0 client credentials; OAuth 2.0 authorization code. Token endpoint: {base}/oauth2/v1/token. 2-legged (service) apps send client ID and secret by Basic auth or a JWT signed with a registered JWKS. 3-legged apps, limited to Certified APIs, get user consent and may use PKCE.
- **Limits:** Response headers report a per-minute OAuth request limit and a per-day API call limit that resets at midnight GMT. Lists page with limit and offset. Bulk data pulls over the API are not accepted. Retry only 502-504 with backoff.
- Keep athenahealth 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

- **Departments** — GET /v1/{practiceid}/departments lists a practice's departments.
- **Changed data feeds** — GET /v1/{practiceid}/documents/patientcase/changed returns queued changes for subscribed events.
- **Subscription events** — GET /v1/{practiceid}/documents/patientcase/changed/subscription/events lists events you can subscribe to.
- **Clinical data (FHIR R4)** — USCDI resources on the FHIR R4 global or site-specific base URL.

## Writes

- **Changed-data subscriptions** — POST /v1/{practiceid}/documents/patientcase/changed/subscription subscribes to all or one event.
- **Remove subscriptions** — DELETE /v1/{practiceid}/documents/patientcase/changed/subscription removes a subscription or events. **Confirm with the user first.**
- **athenaOne records** — athenaOne APIs include write calls across administrative, clinical and financial functions; each needs its endpoint's scope. **Confirm with the user first.**

## Expose it to an ibl.ai agent (MCP)

athenahealth 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`.
   - athenahealth 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

- "List the departments for practice 195900 in the Preview sandbox."
- "Show patient cases that changed since my last sync."
- "Pull this patient's allergies and problem list through the FHIR R4 API."
- "Subscribe to patient case change events for the cardiology department."

## Guardrails

- Records are HIPAA protected health information (PHI). OAuth credentials are tied to one environment, and production data is reachable only for practices that enable the app.
- Request the narrowest athenahealth 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.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- athenahealth API environment URLs: https://docs.athenahealth.com/api/guides/environment-urls
- athenahealth authorization overview: https://docs.athenahealth.com/api/guides/authorization-overview
- athenahealth onboarding overview: https://docs.athenahealth.com/api/guides/onboarding-overview
- This connector on ibl.ai: https://ibl.ai/developer/connectors/athenahealth
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections