# AI Agents & MCP

## What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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.

{% hint style="info" %}
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.).
{% endhint %}

**MCP server URL:**

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

## How to add the MCP server

{% stepper %}
{% step %}

### 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**:

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

#### Claude Code

From your terminal:

```bash
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`:

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

#### VS Code (Copilot)

**CLI:**

bash

```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:

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

#### Windsurf

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

```json
{
  "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](https://modelcontextprotocol.io).

{% endstep %}

{% step %}

### 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.
{% endstep %}
{% endstepper %}

## 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 QuoteConnect 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 QuoteConnect 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."
* "Create an enrollment flow using the EnrollConnect API: create a draft application, update it with applicant data, check the errors array, and submit when ready."

#### 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:

* **QuoteConnect API** – Plan quotes and APTC estimation by location and household
* **Application Deeplink API** – Prefilled off-exchange enrollment flows
* **EnrollConnect API** – Full lifecycle programmatic enrollment
* **Webhooks** – Policy Status (including payment data), Submission Confirmation
* **Integration guide** – Use cases, carrier effective date logic, API changelog
* **Supporting material** – Schemas, enumerations, carrier-specific info

For the full structure, see the [API Reference](/api-reference/endpoints.md) and [Integration Guide](/getting-started/integration-setup.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ichra.healthsherpa.com/getting-started/ai-agents-and-mcp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.