# AI Agents & 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 Medicare MCP server

This documentation site includes a built-in MCP server that exposes the full Medicare 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 or OAuth token is required to use the documentation via MCP. Authentication is only necessary for using the API.
{% endhint %}

**MCP server URL:**

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

## How to add the MCP server

{% stepper %}
{% step %}

### Add the HealthSherpa Medicare MCP server

In your AI or development environment (e.g. Cursor, Claude Code, or another MCP-compatible client), add the HealthSherpa Medicare API MCP server.

#### Cursor

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

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

#### Claude Code

From your terminal:

```bash
claude mcp add --transport http HealthSherpa-Medicare-Docs https://docs.medicare.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-Medicare-Docs": {
      "url": "https://docs.medicare.healthsherpa.com/~gitbook/mcp"
    }
  }
}
```

#### VS Code (Copilot)

**CLI:**

bash

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

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

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

#### Windsurf

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

```json
{
  "mcpServers": {
    "HealthSherpa-Medicare-Docs": {
      "url": "https://docs.medicare.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 Medicare 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 Medicare API offer, and how do they fit together in a contact syncing workflow?"
* "What's the difference between v1 and v2 of the API, and which should I use?"
* "How do I set up and test against the staging environment before going to production?"

#### Building contact synchronization flow

These prompts help when you're actively building the contact synchronization workflow in your product

* "Implement a `/search` endpoint that accepts medicare number alone, OR a combination of name (first name or last name) with at least one of: date of birth, email, or phone, and returns a contact"
* "What fields are required vs optional when creating a contact, and what are the validation rules?"
* "How does agent\_email work and what happens if it doesn't match a HealthSherpa account email?"

#### Handling webhooks

Use these when building the backend that tracks application submission events.

* "Generate a webhook handler that processes the Submission event and maps the payload to our internal application model."
* "What does the webhook submission payload look like and what fields does it include?"

#### Troubleshooting and edge cases

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

* "What error responses can the Create Contact endpoint return, and how should I handle them?"


---

# 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.medicare.healthsherpa.com/integration-guide/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.