How to use Stedi with a coding agent
Guide
Many developers now use AI coding agents like Claude Code and Codex to build software. Non-developers, including providers and practice managers, are building their own tools the same way.
Stedi is an API-first healthcare clearinghouse. We’re designed to work with AI agents. We offer tools, like plain-text docs and test workflows, that make using coding agents easier.
This guide covers how to set up your coding agent for Stedi. You'll learn how to give your agent the right context, test without using real patient data, and connect it to our MCP server.
Give your agent Stedi's docs
The more relevant context your coding agent has, the better code it writes.
Stedi provides its docs as plain-text markdown, a format that agents read more efficiently than standard web pages.
You can give your agent the full Stedi docs as a single file, a structured index so it can pick pages itself, or individual pages.
Full docs: The entire Stedi docs as a single plain-text, markdown file: https://www.stedi.com/docs/llms-full.txt
Doc index: A structured list of links to all doc pages in markdown: https://www.stedi.com/docs/llms.txt
Individual pages: Append
.mdxto any docs page URL to get the page as markdown. Example: https://www.stedi.com/docs/healthcare/test-mode.mdx
For a quick start, give your agent the full docs: https://www.stedi.com/docs/llms-full.txt. Use the doc index and individual doc pages when you're focused on a specific feature, like eligibility checks or claims submission.
Give your agent Stedi's OpenAPI specs
An Application Programming Interface (API) lets an agent – or the software the agent builds – work with Stedi's features using code.
For example, your agent can use Stedi's Real-Time Eligibility Check API to write code that verifies a patient’s insurance using eligibility checks.
What are OpenAPI specs?
An OpenAPI spec is like a blueprint for an API. It describes what endpoints exist, what data you can send them, and what they return. Agents can use OpenAPI specs to write code that uses the API without guessing at field names or data types.
We have OpenAPI specs for every Stedi API endpoint. In addition to docs, give your agent the relevant specs for your use case.
Use case | OpenAPI spec |
Claims submission, including 277CA claim acknowledgments |
|
|
Most workflows also need the payers.json and enrollment.json OpenAPI specs. You need to know the payer ID to send any transaction. Payers may require transaction enrollment before exchanging certain transaction types. Payers always require transaction enrollment for ERAs.
Use Stedi's test workflows
Stedi has two test workflows: one for eligibility checks and one for claims and ERAs. Both let you and your agent test the full Stedi workflow without using real patient data.
Test eligibility checks
Stedi has two API key types: test and production. Test keys let you send mock eligibility checks and get realistic responses – with things like active coverage indicators, copays, and deductibles – without sending real patient data to payers. Mock eligibility checks are free and available on Stedi’s Basic plan.
Note: An API key lets code access your Stedi account using Stedi’s API. Treat it the same way you would a password. Don't share it or store it in plain sight.
Create a test API key
Log in to the Stedi portal.
Click your account name at the top right of the screen.
Select API Keys.
Click Generate new API Key.
Enter a name for your API key. We recommend using a unique name with the
testprefix.Select Test mode.
Click Generate.
Once you have a test key, use one of Stedi's predefined mock eligibility requests to run a check.
For example, here’s a mock eligibility request for Aetna. Paste the request into your agent or run it from your terminal:
curl --request POST \ --url 'https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/eligibility/v3' \ --header 'Authorization: Key <test_api_key>' \ --header 'Content-Type: application/json' \ --data '{ "tradingPartnerServiceId": "60054", "provider": { "organizationName": "Provider Name", "npi": "1999999984" }, "subscriber": { "firstName": "Jane", "lastName": "Doe", "dateOfBirth": "20040404", "memberId": "AETNA12345" }, "encounter": { "serviceTypeCodes": ["30"] } }'
curl --request POST \ --url 'https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/eligibility/v3' \ --header 'Authorization: Key <test_api_key>' \ --header 'Content-Type: application/json' \ --data '{ "tradingPartnerServiceId": "60054", "provider": { "organizationName": "Provider Name", "npi": "1999999984" }, "subscriber": { "firstName": "Jane", "lastName": "Doe", "dateOfBirth": "20040404", "memberId": "AETNA12345" }, "encounter": { "serviceTypeCodes": ["30"] } }'
curl --request POST \ --url 'https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/eligibility/v3' \ --header 'Authorization: Key <test_api_key>' \ --header 'Content-Type: application/json' \ --data '{ "tradingPartnerServiceId": "60054", "provider": { "organizationName": "Provider Name", "npi": "1999999984" }, "subscriber": { "firstName": "Jane", "lastName": "Doe", "dateOfBirth": "20040404", "memberId": "AETNA12345" }, "encounter": { "serviceTypeCodes": ["30"] } }'
Test workflow for claims
Stedi’s test claims workflow doesn’t use test API keys. Instead, you’ll use a production key to submit a claim with a test usage indicator.
Submit a test claim
In most cases, coding agents will use Stedi’s JSON Claims Submission API endpoints. To submit a test claim using these endpoints, set the request’s usageIndicator field to T (Test).
Stedi won't forward the claim to the payer. Instead, you’ll receive a test 277CA acknowledgment from Stedi.
Receive a test ERA
If you send a test claim to the Stedi Test Payer (Payer ID: STEDI), Stedi will return a test ERA.
To test the ERA workflow:
If you haven’t already, create a provider record for the provider you want to test with. Your agent can do this using the Create Provider API endpoint.
Enroll the provider with the Stedi Test Payer for claim payments. Your agent can do this using the Create Enrollment endpoint.
Use a production API key to submit a test claim to the Stedi Test Payer. The following example submits a test professional claim to the Stedi Test Payer using the JSON Professional Claims API endpoint.
curl --request POST \ --url "https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/professionalclaims/v3/submission" \ --header "Authorization: <api_key>" \ --header "Content-Type: application/json" \ --data '{ "tradingPartnerName": "Stedi Test Payer", "tradingPartnerServiceId": "STEDITEST", "usageIndicator": "T", "billing": { "address": { "address1": "123 Some St", "address2": "Floor 1", "city": "A City", "postalCode": "123450000", "state": "NY" }, "contactInformation": { "name": "Test Data Health Services, Inc.", "phoneNumber": "5553334444" }, "employerId": "<TAX-ID-USED-IN-ENROLLMENT>", "npi": "<NPI-USED-IN-ENROLLMENT>", "organizationName": "Therapy Associates", "providerType": "BillingProvider", "taxonomyCode": "2084P0800X" }, "claimInformation": { "benefitsAssignmentCertificationIndicator": "Y", "claimChargeAmount": "109.20", "claimFilingCode": "CI", "claimFrequencyCode": "1", "healthCareCodeInformation": [ { "diagnosisCode": "F1111", "diagnosisTypeCode": "ABK" } ], "patientControlNumber": "<YOUR-CLAIM-ID>", "placeOfServiceCode": "02", "planParticipationCode": "A", "releaseInformationCode": "Y", "serviceFacilityLocation": { "address": { "address1": "1234 Other St", "city": "A City", "postalCode": "123450000", "state": "NY" }, "npi": "1999999984", "organizationName": "Smith Associates" }, "serviceLines": [ { "professionalService": { "compositeDiagnosisCodePointers": { "diagnosisCodePointers": [ "1" ] }, "lineItemChargeAmount": "109.20", "measurementUnit": "UN", "procedureCode": "90837", "procedureIdentifier": "HC", "procedureModifiers": [ "95" ], "serviceUnitCount": "1" }, "providerControlNumber": "111222333", "renderingProvider": { "firstName": "Jane", "lastName": "Smith", "npi": "1999999984", "providerType": "RenderingProvider", "taxonomyCode": "111YP2000X" }, "serviceDate": "20240101" } ], "signatureIndicator": "Y" }, "receiver": { "organizationName": "Stedi" }, "submitter": { "contactInformation": { "name": "Test Data Health Services, Inc.", "phoneNumber": "5552223333" }, "organizationName": "Test Data Health Services, Inc.", "submitterIdentification": "<YOUR-SUBMITTER-ID>" }, "subscriber": { "address": { "address1": "2222 Random St", "city": "A City", "postalCode": "123450000", "state": "NY" }, "dateOfBirth": "20000101", "firstName": "John", "gender": "M", "groupNumber": "3335555", "lastName": "Anon", "memberId": "U7777788888", "paymentResponsibilityLevelCode": "P", "subscriberGroupName": "Test ERAs Group" } }'
curl --request POST \ --url "https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/professionalclaims/v3/submission" \ --header "Authorization: <api_key>" \ --header "Content-Type: application/json" \ --data '{ "tradingPartnerName": "Stedi Test Payer", "tradingPartnerServiceId": "STEDITEST", "usageIndicator": "T", "billing": { "address": { "address1": "123 Some St", "address2": "Floor 1", "city": "A City", "postalCode": "123450000", "state": "NY" }, "contactInformation": { "name": "Test Data Health Services, Inc.", "phoneNumber": "5553334444" }, "employerId": "<TAX-ID-USED-IN-ENROLLMENT>", "npi": "<NPI-USED-IN-ENROLLMENT>", "organizationName": "Therapy Associates", "providerType": "BillingProvider", "taxonomyCode": "2084P0800X" }, "claimInformation": { "benefitsAssignmentCertificationIndicator": "Y", "claimChargeAmount": "109.20", "claimFilingCode": "CI", "claimFrequencyCode": "1", "healthCareCodeInformation": [ { "diagnosisCode": "F1111", "diagnosisTypeCode": "ABK" } ], "patientControlNumber": "<YOUR-CLAIM-ID>", "placeOfServiceCode": "02", "planParticipationCode": "A", "releaseInformationCode": "Y", "serviceFacilityLocation": { "address": { "address1": "1234 Other St", "city": "A City", "postalCode": "123450000", "state": "NY" }, "npi": "1999999984", "organizationName": "Smith Associates" }, "serviceLines": [ { "professionalService": { "compositeDiagnosisCodePointers": { "diagnosisCodePointers": [ "1" ] }, "lineItemChargeAmount": "109.20", "measurementUnit": "UN", "procedureCode": "90837", "procedureIdentifier": "HC", "procedureModifiers": [ "95" ], "serviceUnitCount": "1" }, "providerControlNumber": "111222333", "renderingProvider": { "firstName": "Jane", "lastName": "Smith", "npi": "1999999984", "providerType": "RenderingProvider", "taxonomyCode": "111YP2000X" }, "serviceDate": "20240101" } ], "signatureIndicator": "Y" }, "receiver": { "organizationName": "Stedi" }, "submitter": { "contactInformation": { "name": "Test Data Health Services, Inc.", "phoneNumber": "5552223333" }, "organizationName": "Test Data Health Services, Inc.", "submitterIdentification": "<YOUR-SUBMITTER-ID>" }, "subscriber": { "address": { "address1": "2222 Random St", "city": "A City", "postalCode": "123450000", "state": "NY" }, "dateOfBirth": "20000101", "firstName": "John", "gender": "M", "groupNumber": "3335555", "lastName": "Anon", "memberId": "U7777788888", "paymentResponsibilityLevelCode": "P", "subscriberGroupName": "Test ERAs Group" } }'
curl --request POST \ --url "https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/professionalclaims/v3/submission" \ --header "Authorization: <api_key>" \ --header "Content-Type: application/json" \ --data '{ "tradingPartnerName": "Stedi Test Payer", "tradingPartnerServiceId": "STEDITEST", "usageIndicator": "T", "billing": { "address": { "address1": "123 Some St", "address2": "Floor 1", "city": "A City", "postalCode": "123450000", "state": "NY" }, "contactInformation": { "name": "Test Data Health Services, Inc.", "phoneNumber": "5553334444" }, "employerId": "<TAX-ID-USED-IN-ENROLLMENT>", "npi": "<NPI-USED-IN-ENROLLMENT>", "organizationName": "Therapy Associates", "providerType": "BillingProvider", "taxonomyCode": "2084P0800X" }, "claimInformation": { "benefitsAssignmentCertificationIndicator": "Y", "claimChargeAmount": "109.20", "claimFilingCode": "CI", "claimFrequencyCode": "1", "healthCareCodeInformation": [ { "diagnosisCode": "F1111", "diagnosisTypeCode": "ABK" } ], "patientControlNumber": "<YOUR-CLAIM-ID>", "placeOfServiceCode": "02", "planParticipationCode": "A", "releaseInformationCode": "Y", "serviceFacilityLocation": { "address": { "address1": "1234 Other St", "city": "A City", "postalCode": "123450000", "state": "NY" }, "npi": "1999999984", "organizationName": "Smith Associates" }, "serviceLines": [ { "professionalService": { "compositeDiagnosisCodePointers": { "diagnosisCodePointers": [ "1" ] }, "lineItemChargeAmount": "109.20", "measurementUnit": "UN", "procedureCode": "90837", "procedureIdentifier": "HC", "procedureModifiers": [ "95" ], "serviceUnitCount": "1" }, "providerControlNumber": "111222333", "renderingProvider": { "firstName": "Jane", "lastName": "Smith", "npi": "1999999984", "providerType": "RenderingProvider", "taxonomyCode": "111YP2000X" }, "serviceDate": "20240101" } ], "signatureIndicator": "Y" }, "receiver": { "organizationName": "Stedi" }, "submitter": { "contactInformation": { "name": "Test Data Health Services, Inc.", "phoneNumber": "5552223333" }, "organizationName": "Test Data Health Services, Inc.", "submitterIdentification": "<YOUR-SUBMITTER-ID>" }, "subscriber": { "address": { "address1": "2222 Random St", "city": "A City", "postalCode": "123450000", "state": "NY" }, "dateOfBirth": "20000101", "firstName": "John", "gender": "M", "groupNumber": "3335555", "lastName": "Anon", "memberId": "U7777788888", "paymentResponsibilityLevelCode": "P", "subscriberGroupName": "Test ERAs Group" } }'
You’ll get back a test 277CA acknowledgment from Stedi.
You'll then get a test ERA from Stedi within a few minutes. The ERA will include adjudication data based on the original claim.
For more details, see Test claims workflow in the Stedi docs.
Connect to Stedi's MCP server
Most of the time, a coding agent writes code that you or your application runs later. For that, the docs and OpenAPI specs are all you need.
Model Context Protocol (MCP) is a way for AI agents to connect to external services, like Stedi, without writing their own code. An MCP server exposes related tools that your agent can use directly.
You can use Stedi’s MCP server to let agents run real-time eligibility checks. The server is useful in two cases:
You're building an agent (like an AI voice agent) that needs to run eligibility checks itself. This is different from using a coding agent, like Claude Code or Codex, to build a tool.
You want to use your coding agent to make one-off eligibility checks without writing code.
The server is a thin wrapper around Stedi’s JSON Real-Time Eligibility Check and Payers Search API endpoints. It exposes two related tools:
Tool | What it does |
| Runs a real-time eligibility check |
| Finds a payer by ID or name. Partial matches and typos work. |
It also has built-in logic for recovering failed eligibility checks.
How to connect to Stedi’s MCP server
You can connect your agent to Stedi's MCP server using a Stedi production API key and OAuth. We recommend using an API key for simplicity.
Before connecting to Stedi’s MCP server, export your production API key to an environment variable. For example:
export STEDI_API_KEY=<your-stedi-api-key>
export STEDI_API_KEY=<your-stedi-api-key>
export STEDI_API_KEY=<your-stedi-api-key>
Note: An environment variable lets you save your API key under a short name and reuse it across commands. It also helps you avoid accidentally exposing your key to your agent or storing it somewhere others can see it.
Below are steps for connecting popular coding agents to Stedi’s MCP server using the STEDI_API_KEY environment variable.
Claude Code
claude mcp add --transport http stedi-healthcare \ https://mcp.us.stedi.com/2025-07-11/mcp \ --header "Authorization: $STEDI_API_KEY"
claude mcp add --transport http stedi-healthcare \ https://mcp.us.stedi.com/2025-07-11/mcp \ --header "Authorization: $STEDI_API_KEY"
claude mcp add --transport http stedi-healthcare \ https://mcp.us.stedi.com/2025-07-11/mcp \ --header "Authorization: $STEDI_API_KEY"
Codex
Edit ~/.codex/config.toml directly:
[mcp_servers.stedi-healthcare] url = "https://mcp.us.stedi.com/2025-07-11/mcp" [mcp_servers.stedi-healthcare.http_headers] Authorization = "${STEDI_API_KEY}"
[mcp_servers.stedi-healthcare] url = "https://mcp.us.stedi.com/2025-07-11/mcp" [mcp_servers.stedi-healthcare.http_headers] Authorization = "${STEDI_API_KEY}"
[mcp_servers.stedi-healthcare] url = "https://mcp.us.stedi.com/2025-07-11/mcp" [mcp_servers.stedi-healthcare.http_headers] Authorization = "${STEDI_API_KEY}"
Gemini CLI
gemini mcp add --transport http \ --header "Authorization: $STEDI_API_KEY" \ stedi-healthcare \ https://mcp.us.stedi.com/2025-07-11/mcp
gemini mcp add --transport http \ --header "Authorization: $STEDI_API_KEY" \ stedi-healthcare \ https://mcp.us.stedi.com/2025-07-11/mcp
gemini mcp add --transport http \ --header "Authorization: $STEDI_API_KEY" \ stedi-healthcare \ https://mcp.us.stedi.com/2025-07-11/mcp
Do I need a BAA to use real patient data with an agent?
Most likely. If you're using our MCP server with a third-party tool like Claude Code or Codex, follow your organization's data handling policies to stay compliant with HIPAA and other applicable requirements. For example, your organization likely requires a BAA with any third-party tool before using the tool with Stedi's MCP server.
How to keep patient data out of your agent’s context
The easiest way to avoid BAA and HIPAA concerns is to keep real patient data out of your agent's context. Here are some best practices:
Only use test workflows during development. These workflows don't require real patient data.
Don't paste patient data into prompts. Anything you paste into the agent's context is sent to the model provider. Use test fixtures instead.
Get started
With a coding agent to help, you can get up and running with Stedi in minutes to hours.
To get started, sign up for our Basic plan. It's free, takes less than two minutes, and doesn't require a credit card. You can also reach out using our contact form.
After you create an account, our team will get in touch. Ask for a free trial to evaluate Stedi. During the trial, you’ll get full production access.
Many developers now use AI coding agents like Claude Code and Codex to build software. Non-developers, including providers and practice managers, are building their own tools the same way.
Stedi is an API-first healthcare clearinghouse. We’re designed to work with AI agents. We offer tools, like plain-text docs and test workflows, that make using coding agents easier.
This guide covers how to set up your coding agent for Stedi. You'll learn how to give your agent the right context, test without using real patient data, and connect it to our MCP server.
Give your agent Stedi's docs
The more relevant context your coding agent has, the better code it writes.
Stedi provides its docs as plain-text markdown, a format that agents read more efficiently than standard web pages.
You can give your agent the full Stedi docs as a single file, a structured index so it can pick pages itself, or individual pages.
Full docs: The entire Stedi docs as a single plain-text, markdown file: https://www.stedi.com/docs/llms-full.txt
Doc index: A structured list of links to all doc pages in markdown: https://www.stedi.com/docs/llms.txt
Individual pages: Append
.mdxto any docs page URL to get the page as markdown. Example: https://www.stedi.com/docs/healthcare/test-mode.mdx
For a quick start, give your agent the full docs: https://www.stedi.com/docs/llms-full.txt. Use the doc index and individual doc pages when you're focused on a specific feature, like eligibility checks or claims submission.
Give your agent Stedi's OpenAPI specs
An Application Programming Interface (API) lets an agent – or the software the agent builds – work with Stedi's features using code.
For example, your agent can use Stedi's Real-Time Eligibility Check API to write code that verifies a patient’s insurance using eligibility checks.
What are OpenAPI specs?
An OpenAPI spec is like a blueprint for an API. It describes what endpoints exist, what data you can send them, and what they return. Agents can use OpenAPI specs to write code that uses the API without guessing at field names or data types.
We have OpenAPI specs for every Stedi API endpoint. In addition to docs, give your agent the relevant specs for your use case.
Use case | OpenAPI spec |
Claims submission, including 277CA claim acknowledgments |
|
|
Most workflows also need the payers.json and enrollment.json OpenAPI specs. You need to know the payer ID to send any transaction. Payers may require transaction enrollment before exchanging certain transaction types. Payers always require transaction enrollment for ERAs.
Use Stedi's test workflows
Stedi has two test workflows: one for eligibility checks and one for claims and ERAs. Both let you and your agent test the full Stedi workflow without using real patient data.
Test eligibility checks
Stedi has two API key types: test and production. Test keys let you send mock eligibility checks and get realistic responses – with things like active coverage indicators, copays, and deductibles – without sending real patient data to payers. Mock eligibility checks are free and available on Stedi’s Basic plan.
Note: An API key lets code access your Stedi account using Stedi’s API. Treat it the same way you would a password. Don't share it or store it in plain sight.
Create a test API key
Log in to the Stedi portal.
Click your account name at the top right of the screen.
Select API Keys.
Click Generate new API Key.
Enter a name for your API key. We recommend using a unique name with the
testprefix.Select Test mode.
Click Generate.
Once you have a test key, use one of Stedi's predefined mock eligibility requests to run a check.
For example, here’s a mock eligibility request for Aetna. Paste the request into your agent or run it from your terminal:
curl --request POST \ --url 'https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/eligibility/v3' \ --header 'Authorization: Key <test_api_key>' \ --header 'Content-Type: application/json' \ --data '{ "tradingPartnerServiceId": "60054", "provider": { "organizationName": "Provider Name", "npi": "1999999984" }, "subscriber": { "firstName": "Jane", "lastName": "Doe", "dateOfBirth": "20040404", "memberId": "AETNA12345" }, "encounter": { "serviceTypeCodes": ["30"] } }'
Test workflow for claims
Stedi’s test claims workflow doesn’t use test API keys. Instead, you’ll use a production key to submit a claim with a test usage indicator.
Submit a test claim
In most cases, coding agents will use Stedi’s JSON Claims Submission API endpoints. To submit a test claim using these endpoints, set the request’s usageIndicator field to T (Test).
Stedi won't forward the claim to the payer. Instead, you’ll receive a test 277CA acknowledgment from Stedi.
Receive a test ERA
If you send a test claim to the Stedi Test Payer (Payer ID: STEDI), Stedi will return a test ERA.
To test the ERA workflow:
If you haven’t already, create a provider record for the provider you want to test with. Your agent can do this using the Create Provider API endpoint.
Enroll the provider with the Stedi Test Payer for claim payments. Your agent can do this using the Create Enrollment endpoint.
Use a production API key to submit a test claim to the Stedi Test Payer. The following example submits a test professional claim to the Stedi Test Payer using the JSON Professional Claims API endpoint.
curl --request POST \ --url "https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/professionalclaims/v3/submission" \ --header "Authorization: <api_key>" \ --header "Content-Type: application/json" \ --data '{ "tradingPartnerName": "Stedi Test Payer", "tradingPartnerServiceId": "STEDITEST", "usageIndicator": "T", "billing": { "address": { "address1": "123 Some St", "address2": "Floor 1", "city": "A City", "postalCode": "123450000", "state": "NY" }, "contactInformation": { "name": "Test Data Health Services, Inc.", "phoneNumber": "5553334444" }, "employerId": "<TAX-ID-USED-IN-ENROLLMENT>", "npi": "<NPI-USED-IN-ENROLLMENT>", "organizationName": "Therapy Associates", "providerType": "BillingProvider", "taxonomyCode": "2084P0800X" }, "claimInformation": { "benefitsAssignmentCertificationIndicator": "Y", "claimChargeAmount": "109.20", "claimFilingCode": "CI", "claimFrequencyCode": "1", "healthCareCodeInformation": [ { "diagnosisCode": "F1111", "diagnosisTypeCode": "ABK" } ], "patientControlNumber": "<YOUR-CLAIM-ID>", "placeOfServiceCode": "02", "planParticipationCode": "A", "releaseInformationCode": "Y", "serviceFacilityLocation": { "address": { "address1": "1234 Other St", "city": "A City", "postalCode": "123450000", "state": "NY" }, "npi": "1999999984", "organizationName": "Smith Associates" }, "serviceLines": [ { "professionalService": { "compositeDiagnosisCodePointers": { "diagnosisCodePointers": [ "1" ] }, "lineItemChargeAmount": "109.20", "measurementUnit": "UN", "procedureCode": "90837", "procedureIdentifier": "HC", "procedureModifiers": [ "95" ], "serviceUnitCount": "1" }, "providerControlNumber": "111222333", "renderingProvider": { "firstName": "Jane", "lastName": "Smith", "npi": "1999999984", "providerType": "RenderingProvider", "taxonomyCode": "111YP2000X" }, "serviceDate": "20240101" } ], "signatureIndicator": "Y" }, "receiver": { "organizationName": "Stedi" }, "submitter": { "contactInformation": { "name": "Test Data Health Services, Inc.", "phoneNumber": "5552223333" }, "organizationName": "Test Data Health Services, Inc.", "submitterIdentification": "<YOUR-SUBMITTER-ID>" }, "subscriber": { "address": { "address1": "2222 Random St", "city": "A City", "postalCode": "123450000", "state": "NY" }, "dateOfBirth": "20000101", "firstName": "John", "gender": "M", "groupNumber": "3335555", "lastName": "Anon", "memberId": "U7777788888", "paymentResponsibilityLevelCode": "P", "subscriberGroupName": "Test ERAs Group" } }'
You’ll get back a test 277CA acknowledgment from Stedi.
You'll then get a test ERA from Stedi within a few minutes. The ERA will include adjudication data based on the original claim.
For more details, see Test claims workflow in the Stedi docs.
Connect to Stedi's MCP server
Most of the time, a coding agent writes code that you or your application runs later. For that, the docs and OpenAPI specs are all you need.
Model Context Protocol (MCP) is a way for AI agents to connect to external services, like Stedi, without writing their own code. An MCP server exposes related tools that your agent can use directly.
You can use Stedi’s MCP server to let agents run real-time eligibility checks. The server is useful in two cases:
You're building an agent (like an AI voice agent) that needs to run eligibility checks itself. This is different from using a coding agent, like Claude Code or Codex, to build a tool.
You want to use your coding agent to make one-off eligibility checks without writing code.
The server is a thin wrapper around Stedi’s JSON Real-Time Eligibility Check and Payers Search API endpoints. It exposes two related tools:
Tool | What it does |
| Runs a real-time eligibility check |
| Finds a payer by ID or name. Partial matches and typos work. |
It also has built-in logic for recovering failed eligibility checks.
How to connect to Stedi’s MCP server
You can connect your agent to Stedi's MCP server using a Stedi production API key and OAuth. We recommend using an API key for simplicity.
Before connecting to Stedi’s MCP server, export your production API key to an environment variable. For example:
export STEDI_API_KEY=<your-stedi-api-key>
Note: An environment variable lets you save your API key under a short name and reuse it across commands. It also helps you avoid accidentally exposing your key to your agent or storing it somewhere others can see it.
Below are steps for connecting popular coding agents to Stedi’s MCP server using the STEDI_API_KEY environment variable.
Claude Code
claude mcp add --transport http stedi-healthcare \ https://mcp.us.stedi.com/2025-07-11/mcp \ --header "Authorization: $STEDI_API_KEY"
Codex
Edit ~/.codex/config.toml directly:
[mcp_servers.stedi-healthcare] url = "https://mcp.us.stedi.com/2025-07-11/mcp" [mcp_servers.stedi-healthcare.http_headers] Authorization = "${STEDI_API_KEY}"
Gemini CLI
gemini mcp add --transport http \ --header "Authorization: $STEDI_API_KEY" \ stedi-healthcare \ https://mcp.us.stedi.com/2025-07-11/mcp
Do I need a BAA to use real patient data with an agent?
Most likely. If you're using our MCP server with a third-party tool like Claude Code or Codex, follow your organization's data handling policies to stay compliant with HIPAA and other applicable requirements. For example, your organization likely requires a BAA with any third-party tool before using the tool with Stedi's MCP server.
How to keep patient data out of your agent’s context
The easiest way to avoid BAA and HIPAA concerns is to keep real patient data out of your agent's context. Here are some best practices:
Only use test workflows during development. These workflows don't require real patient data.
Don't paste patient data into prompts. Anything you paste into the agent's context is sent to the model provider. Use test fixtures instead.
Get started
With a coding agent to help, you can get up and running with Stedi in minutes to hours.
To get started, sign up for our Basic plan. It's free, takes less than two minutes, and doesn't require a credit card. You can also reach out using our contact form.
After you create an account, our team will get in touch. Ask for a free trial to evaluate Stedi. During the trial, you’ll get full production access.
Many developers now use AI coding agents like Claude Code and Codex to build software. Non-developers, including providers and practice managers, are building their own tools the same way.
Stedi is an API-first healthcare clearinghouse. We’re designed to work with AI agents. We offer tools, like plain-text docs and test workflows, that make using coding agents easier.
This guide covers how to set up your coding agent for Stedi. You'll learn how to give your agent the right context, test without using real patient data, and connect it to our MCP server.
Give your agent Stedi's docs
The more relevant context your coding agent has, the better code it writes.
Stedi provides its docs as plain-text markdown, a format that agents read more efficiently than standard web pages.
You can give your agent the full Stedi docs as a single file, a structured index so it can pick pages itself, or individual pages.
Full docs: The entire Stedi docs as a single plain-text, markdown file: https://www.stedi.com/docs/llms-full.txt
Doc index: A structured list of links to all doc pages in markdown: https://www.stedi.com/docs/llms.txt
Individual pages: Append
.mdxto any docs page URL to get the page as markdown. Example: https://www.stedi.com/docs/healthcare/test-mode.mdx
For a quick start, give your agent the full docs: https://www.stedi.com/docs/llms-full.txt. Use the doc index and individual doc pages when you're focused on a specific feature, like eligibility checks or claims submission.
Give your agent Stedi's OpenAPI specs
An Application Programming Interface (API) lets an agent – or the software the agent builds – work with Stedi's features using code.
For example, your agent can use Stedi's Real-Time Eligibility Check API to write code that verifies a patient’s insurance using eligibility checks.
What are OpenAPI specs?
An OpenAPI spec is like a blueprint for an API. It describes what endpoints exist, what data you can send them, and what they return. Agents can use OpenAPI specs to write code that uses the API without guessing at field names or data types.
We have OpenAPI specs for every Stedi API endpoint. In addition to docs, give your agent the relevant specs for your use case.
Use case | OpenAPI spec |
Claims submission, including 277CA claim acknowledgments |
|
|
Most workflows also need the payers.json and enrollment.json OpenAPI specs. You need to know the payer ID to send any transaction. Payers may require transaction enrollment before exchanging certain transaction types. Payers always require transaction enrollment for ERAs.
Use Stedi's test workflows
Stedi has two test workflows: one for eligibility checks and one for claims and ERAs. Both let you and your agent test the full Stedi workflow without using real patient data.
Test eligibility checks
Stedi has two API key types: test and production. Test keys let you send mock eligibility checks and get realistic responses – with things like active coverage indicators, copays, and deductibles – without sending real patient data to payers. Mock eligibility checks are free and available on Stedi’s Basic plan.
Note: An API key lets code access your Stedi account using Stedi’s API. Treat it the same way you would a password. Don't share it or store it in plain sight.
Create a test API key
Log in to the Stedi portal.
Click your account name at the top right of the screen.
Select API Keys.
Click Generate new API Key.
Enter a name for your API key. We recommend using a unique name with the
testprefix.Select Test mode.
Click Generate.
Once you have a test key, use one of Stedi's predefined mock eligibility requests to run a check.
For example, here’s a mock eligibility request for Aetna. Paste the request into your agent or run it from your terminal:
curl --request POST \ --url 'https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/eligibility/v3' \ --header 'Authorization: Key <test_api_key>' \ --header 'Content-Type: application/json' \ --data '{ "tradingPartnerServiceId": "60054", "provider": { "organizationName": "Provider Name", "npi": "1999999984" }, "subscriber": { "firstName": "Jane", "lastName": "Doe", "dateOfBirth": "20040404", "memberId": "AETNA12345" }, "encounter": { "serviceTypeCodes": ["30"] } }'
Test workflow for claims
Stedi’s test claims workflow doesn’t use test API keys. Instead, you’ll use a production key to submit a claim with a test usage indicator.
Submit a test claim
In most cases, coding agents will use Stedi’s JSON Claims Submission API endpoints. To submit a test claim using these endpoints, set the request’s usageIndicator field to T (Test).
Stedi won't forward the claim to the payer. Instead, you’ll receive a test 277CA acknowledgment from Stedi.
Receive a test ERA
If you send a test claim to the Stedi Test Payer (Payer ID: STEDI), Stedi will return a test ERA.
To test the ERA workflow:
If you haven’t already, create a provider record for the provider you want to test with. Your agent can do this using the Create Provider API endpoint.
Enroll the provider with the Stedi Test Payer for claim payments. Your agent can do this using the Create Enrollment endpoint.
Use a production API key to submit a test claim to the Stedi Test Payer. The following example submits a test professional claim to the Stedi Test Payer using the JSON Professional Claims API endpoint.
curl --request POST \ --url "https://healthcare.us.stedi.com/2024-04-01/change/medicalnetwork/professionalclaims/v3/submission" \ --header "Authorization: <api_key>" \ --header "Content-Type: application/json" \ --data '{ "tradingPartnerName": "Stedi Test Payer", "tradingPartnerServiceId": "STEDITEST", "usageIndicator": "T", "billing": { "address": { "address1": "123 Some St", "address2": "Floor 1", "city": "A City", "postalCode": "123450000", "state": "NY" }, "contactInformation": { "name": "Test Data Health Services, Inc.", "phoneNumber": "5553334444" }, "employerId": "<TAX-ID-USED-IN-ENROLLMENT>", "npi": "<NPI-USED-IN-ENROLLMENT>", "organizationName": "Therapy Associates", "providerType": "BillingProvider", "taxonomyCode": "2084P0800X" }, "claimInformation": { "benefitsAssignmentCertificationIndicator": "Y", "claimChargeAmount": "109.20", "claimFilingCode": "CI", "claimFrequencyCode": "1", "healthCareCodeInformation": [ { "diagnosisCode": "F1111", "diagnosisTypeCode": "ABK" } ], "patientControlNumber": "<YOUR-CLAIM-ID>", "placeOfServiceCode": "02", "planParticipationCode": "A", "releaseInformationCode": "Y", "serviceFacilityLocation": { "address": { "address1": "1234 Other St", "city": "A City", "postalCode": "123450000", "state": "NY" }, "npi": "1999999984", "organizationName": "Smith Associates" }, "serviceLines": [ { "professionalService": { "compositeDiagnosisCodePointers": { "diagnosisCodePointers": [ "1" ] }, "lineItemChargeAmount": "109.20", "measurementUnit": "UN", "procedureCode": "90837", "procedureIdentifier": "HC", "procedureModifiers": [ "95" ], "serviceUnitCount": "1" }, "providerControlNumber": "111222333", "renderingProvider": { "firstName": "Jane", "lastName": "Smith", "npi": "1999999984", "providerType": "RenderingProvider", "taxonomyCode": "111YP2000X" }, "serviceDate": "20240101" } ], "signatureIndicator": "Y" }, "receiver": { "organizationName": "Stedi" }, "submitter": { "contactInformation": { "name": "Test Data Health Services, Inc.", "phoneNumber": "5552223333" }, "organizationName": "Test Data Health Services, Inc.", "submitterIdentification": "<YOUR-SUBMITTER-ID>" }, "subscriber": { "address": { "address1": "2222 Random St", "city": "A City", "postalCode": "123450000", "state": "NY" }, "dateOfBirth": "20000101", "firstName": "John", "gender": "M", "groupNumber": "3335555", "lastName": "Anon", "memberId": "U7777788888", "paymentResponsibilityLevelCode": "P", "subscriberGroupName": "Test ERAs Group" } }'
You’ll get back a test 277CA acknowledgment from Stedi.
You'll then get a test ERA from Stedi within a few minutes. The ERA will include adjudication data based on the original claim.
For more details, see Test claims workflow in the Stedi docs.
Connect to Stedi's MCP server
Most of the time, a coding agent writes code that you or your application runs later. For that, the docs and OpenAPI specs are all you need.
Model Context Protocol (MCP) is a way for AI agents to connect to external services, like Stedi, without writing their own code. An MCP server exposes related tools that your agent can use directly.
You can use Stedi’s MCP server to let agents run real-time eligibility checks. The server is useful in two cases:
You're building an agent (like an AI voice agent) that needs to run eligibility checks itself. This is different from using a coding agent, like Claude Code or Codex, to build a tool.
You want to use your coding agent to make one-off eligibility checks without writing code.
The server is a thin wrapper around Stedi’s JSON Real-Time Eligibility Check and Payers Search API endpoints. It exposes two related tools:
Tool | What it does |
| Runs a real-time eligibility check |
| Finds a payer by ID or name. Partial matches and typos work. |
It also has built-in logic for recovering failed eligibility checks.
How to connect to Stedi’s MCP server
You can connect your agent to Stedi's MCP server using a Stedi production API key and OAuth. We recommend using an API key for simplicity.
Before connecting to Stedi’s MCP server, export your production API key to an environment variable. For example:
export STEDI_API_KEY=<your-stedi-api-key>
Note: An environment variable lets you save your API key under a short name and reuse it across commands. It also helps you avoid accidentally exposing your key to your agent or storing it somewhere others can see it.
Below are steps for connecting popular coding agents to Stedi’s MCP server using the STEDI_API_KEY environment variable.
Claude Code
claude mcp add --transport http stedi-healthcare \ https://mcp.us.stedi.com/2025-07-11/mcp \ --header "Authorization: $STEDI_API_KEY"
Codex
Edit ~/.codex/config.toml directly:
[mcp_servers.stedi-healthcare] url = "https://mcp.us.stedi.com/2025-07-11/mcp" [mcp_servers.stedi-healthcare.http_headers] Authorization = "${STEDI_API_KEY}"
Gemini CLI
gemini mcp add --transport http \ --header "Authorization: $STEDI_API_KEY" \ stedi-healthcare \ https://mcp.us.stedi.com/2025-07-11/mcp
Do I need a BAA to use real patient data with an agent?
Most likely. If you're using our MCP server with a third-party tool like Claude Code or Codex, follow your organization's data handling policies to stay compliant with HIPAA and other applicable requirements. For example, your organization likely requires a BAA with any third-party tool before using the tool with Stedi's MCP server.
How to keep patient data out of your agent’s context
The easiest way to avoid BAA and HIPAA concerns is to keep real patient data out of your agent's context. Here are some best practices:
Only use test workflows during development. These workflows don't require real patient data.
Don't paste patient data into prompts. Anything you paste into the agent's context is sent to the model provider. Use test fixtures instead.
Get started
With a coding agent to help, you can get up and running with Stedi in minutes to hours.
To get started, sign up for our Basic plan. It's free, takes less than two minutes, and doesn't require a credit card. You can also reach out using our contact form.
After you create an account, our team will get in touch. Ask for a free trial to evaluate Stedi. During the trial, you’ll get full production access.
Share
Get started with Stedi
Get started with Stedi
Automate healthcare transactions with developer-friendly APIs that support thousands of payers. Contact us to learn more and speak to the team.
Get updates on what’s new at Stedi
Get updates on what’s new at Stedi
Get updates on what’s new at Stedi
Product
Developers
Resources
Get updates on what’s new at Stedi
Backed by
Stedi and the S design mark are registered trademarks of Stedi, Inc. All names, logos, and brands of third parties listed on our site are trademarks of their respective owners (including “X12”, which is a trademark of X12 Incorporated). Stedi, Inc. and its products and services are not endorsed by, sponsored by, or affiliated with these third parties. Our use of these names, logos, and brands is for identification purposes only, and does not imply any such endorsement, sponsorship, or affiliation.
Product
Developers
Resources
Get updates on what’s new at Stedi
Backed by
Stedi and the S design mark are registered trademarks of Stedi, Inc. All names, logos, and brands of third parties listed on our site are trademarks of their respective owners (including “X12”, which is a trademark of X12 Incorporated). Stedi, Inc. and its products and services are not endorsed by, sponsored by, or affiliated with these third parties. Our use of these names, logos, and brands is for identification purposes only, and does not imply any such endorsement, sponsorship, or affiliation.
Product
Developers
Resources
Get updates on what’s new at Stedi
Backed by
Stedi and the S design mark are registered trademarks of Stedi, Inc. All names, logos, and brands of third parties listed on our site are trademarks of their respective owners (including “X12”, which is a trademark of X12 Incorporated). Stedi, Inc. and its products and services are not endorsed by, sponsored by, or affiliated with these third parties. Our use of these names, logos, and brands is for identification purposes only, and does not imply any such endorsement, sponsorship, or affiliation.