AI Agents & MCP

What is MCP?

The Model Context Protocol (MCP) lets AI assistants and development tools pull documentation and context from external sources. With MCP, an AI can answer questions and generate code using up-to-date API details instead of relying only on its training data.

HealthSherpa ICHRA MCP server

This documentation site includes a built-in MCP server that exposes the full ICHRA API documentation for AI-assisted search. You send a natural-language or keyword query and receive relevant excerpts with links back to the source pages.

No API key is required to use the documentation via MCP. API keys are only needed when calling the live ICHRA APIs (Quoting, APTC, Application Deeplink, etc.).

MCP server URL:

https://docs.ichra.healthsherpa.com/~gitbook/mcp

How to add the MCP server

1

Add the HealthSherpa ICHRA MCP server

In your AI or development environment (e.g. Cursor, Claude Code, or another MCP-compatible client), add the HealthSherpa ICHRA API MCP server. Use the server URL or package provided by HealthSherpa or your onboarding representative.

Cursor

Add to .cursor/mcp.json in your project root, or go to Cursor Settings → MCP → Add new global MCP server:

{
  "mcpServers": {
    "HealthSherpa-ICHRA-Docs": {
      "url": "https://docs.ichra.healthsherpa.com/~gitbook/mcp"
    }
  }
}

Claude Code

From your terminal:

claude mcp add --transport http HealthSherpa-ICHRA-Docs https://docs.ichra.healthsherpa.com/~gitbook/mcp

Add --scope user to make it available across all projects, or --scope project to share it with your team via .mcp.json.

Claude Desktop

Open Settings → Developer → Edit Config and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "HealthSherpa-ICHRA-Docs": {
      "url": "https://docs.ichra.healthsherpa.com/~gitbook/mcp"
    }
  }
}

VS Code (Copilot)

CLI:

bash

code --add-mcp '{"name":"HealthSherpa-ICHRA-Docs","type":"http","url":"https://docs.ichra.healthsherpa.com/~gitbook/mcp"}'

Or add to .vscode/mcp.json in your project root:

{
  "servers": {
    "HealthSherpa-ICHRA-Docs": {
      "url": "https://docs.ichra.healthsherpa.com/~gitbook/mcp"
    }
  }
}

Windsurf

Add to .windsurf/mcp.json in your project root:

{
  "mcpServers": {
    "HealthSherpa-ICHRA-Docs": {
      "url": "https://docs.ichra.healthsherpa.com/~gitbook/mcp"
    }
  }
}

Other MCP clients

Any tool that supports MCP over HTTP can connect using the server URL above. Refer to your tool's documentation for the specific configuration format. For general MCP setup, see the Model Context Protocol docs.

2

Verify and use

Once configured, ask your AI assistant questions about the ICHRA API in natural language. The assistant will search the documentation and return relevant excerpts with links to the full pages.

Usage

Planning your integration

Use MCP to explore the API surface and plan your integration before writing any code.

• "What endpoints does the HealthSherpa ICHRA API offer, and how do they fit together in an enrollment workflow?"

• "What data do I need to collect from an employee before I can generate quotes and deeplink them into enrollment?"

• "How can I optimize my application to offer off-exchange and on-exchange plans through HealthSherpa?"

Building a quoting and enrollment flow

These prompts help when you're actively building the plan shopping and enrollment experience for your platform.

• "Implement a /quotes endpoint that accepts household members as input, calls the HealthSherpa Quoting API, and returns the plans grouped by metal level with premiums and deductibles."

• "Integrate APTC estimation into the quoting service — after fetching quotes, call the APTC Estimator for the household, then net the subsidy off each plan's premium before returning the response."

• "Wire up the enrollment deeplink flow end-to-end: collect the required Application Deeplink fields from our member record, POST to the Deeplink API, and redirect the employee to the returned HealthSherpa URL."

Handling webhooks and post-enrollment

Use these when building the backend that tracks application and policy lifecycle events.

• "Generate a webhook handler that processes both Submission Confirmation and Policy Status events and maps the payload to our internal enrollment model."

• "What are the possible policy status values, and what state transitions should my system account for?"

• "How do I reconcile the payment object in the Policy Status webhook with our billing records?"

Troubleshooting and edge cases

When you hit something unexpected during development, MCP can surface the relevant docs fast.

• "What effective date logic applies for mid-month enrollments by carrier?"

• "Which SEP reasons are valid for off-exchange deeplink enrollment, and do they vary by carrier?"

• "What error responses can the Quoting API return, and how should I handle them?"

MCP Fallback

If MCP is unavailable, agents can use direct markdown URLs by appending .md to docs pages.

Examples:

• https://docs.ichra.healthsherpa.com/getting-started/integration-playbooks.md

• https://docs.ichra.healthsherpa.com/api-reference/endpoints/quoting-api.md

• https://docs.ichra.healthsherpa.com/api-reference/supporting-material/fips-county-codes.md

What's available

The content available via MCP matches the ICHRA API documentation and includes:

• Quoting API – Plan quotes by location and household

• APTC Estimator API – Advance Premium Tax Credit estimation

• Application Deeplink API – Prefilled off-exchange enrollment flows

• Webhooks – Policy Status (including payment data), Submission Confirmation

• Integration guide – Use cases, carrier effective date logic, API changelog

• Supporting material – Schemas, enumerations, carrier-specific deeplink and SEP info

For the full structure, see the API Reference and Integration Guide.