---
name: iblai-connect-availity
description: "Read and write Availity data through the Availity APIs (HIPAA Transaction APIs, Claim Attachments API, Remittance Data API beta) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Availity data, or to set up an Availity MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Availity connector for AI agents

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

Availity connects healthcare providers with health plans for administrative transactions: eligibility and benefits, claim status, prior authorization (service reviews), claim attachments and remittance data.

## Auth & conventions

- **API:** Availity APIs (HIPAA Transaction APIs, Claim Attachments API, Remittance Data API beta) (REST). REST versions of X12 transactions: Coverages (270/271), Claim Statuses (276/277) and Service Reviews (278), plus payer list and payer configuration lookups. Requests are asynchronous: poll the returned location until complete.
- **Base URL:** https://api.availity.com/availity/v1/
- **Access:** Partner or license program. Create a Dev Portal account and an app, then subscribe to the Demo plan (auto-approved, canned responses). Live data needs a contract through an Availity Trading Partner Manager to move to the Standard plan.
- **Auth:** OAuth 2.0 client credentials. POST https://api.availity.com/availity/v1/token with grant_type client_credentials and scope hipaa. Tokens last 5 minutes. Send them as Authorization: Bearer on each call.
- **Limits:** Demo plan: 5 transactions per second and 500 per day. Standard plan: 100 per second and 100,000 per day. HTTP 429 means retry after 1 second, or after midnight UTC for the daily cap.
- Keep Availity 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

- **Eligibility and benefits** — GET /v1/coverages/{id} returns a coverage (270/271) result; status 0 is in progress, 4 is complete.
- **Claim status** — GET /v1/claim-statuses starts or checks a 276/277 inquiry; GET /v1/claim-statuses/{id} returns the full result.
- **Service reviews** — GET /v2/service-reviews searches prior authorizations; GET /v2/service-reviews/{id} returns one.
- **Payer list** — GET /availity-payer-list returns payers and the transactions they support.
- **Payer configurations** — GET /v1/configurations returns a payer's field and validation rules.
- **Attachment status** — GET /medical-attachments/ma/external/rest/status/{requestId} checks a submitted attachment.

## Writes

- **Eligibility inquiry** — POST /v1/coverages sends an eligibility and benefits request to the payer.
- **Prior authorization** — POST /v2/service-reviews submits a 278 service review to the health plan. **Confirm with the user first.**
- **Update or void review** — PUT /v2/service-reviews updates a review; DELETE /v2/service-reviews/{id} voids it. **Confirm with the user first.**
- **Claim attachments** — POST /medical-attachments/ma/external/rest/response submits an attachment to a claim. **Confirm with the user first.**

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

Availity 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`.
   - For an API key or service credential use `auth_type=token` with `auth_scope=platform` for one key across the organization, or scope it to a single agent for one key per agent.
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

- "Check eligibility and benefits for this member with Florida Blue for an office visit today."
- "What is the status of the claim we sent for this patient on March 3?"
- "Look up whether the prior authorization for this MRI has been approved."
- "List payers in Availity that support electronic claim status."

## Guardrails

- Member eligibility, claim and authorization data is HIPAA protected health information (PHI), exchanged as HIPAA-standard X12 transactions between providers and health plans.
- Request the narrowest Availity 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

- Availity Developer Portal: https://developer.availity.com/
- Availity API Guide: https://developer.availity.com/blog/2025/3/25/availity-api-guide
- Availity HIPAA Transaction APIs: https://developer.availity.com/blog/2025/3/25/hipaa-transactions
- This connector on ibl.ai: https://ibl.ai/developer/connectors/availity
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections