Using the MCP

Worked examples — real customer questions mapped to tool calls, chaining patterns, and how to test the server by hand.

This guide assumes your client is already connected — see MCP Server for the endpoint and connect instructions. Here we cover what to actually do with the six tools: which one answers which question, how they chain together, and how to verify the server by hand.

From question to tool call

Every tool returns the same JSON as its REST counterpart, so the examples below show the tool arguments and the shape that comes back.

"Are you available in my state?"

Call list_states with no arguments. It returns every state with bookable care:

{ "states": [{ "code": "OH", "name": "Ohio", "appointmentTypeCount": 6 }, ...] }

If the customer's state is in the list, care is bookable there. Every other tool is scoped by these code values.

"Do you take Aetna?"

Call list_insurances with the customer's state:

// arguments
{ "state": "OH" }

// result
{ "state": "OH", "insurances": ["Aetna", "Blue Cross Blue Shield", "Cigna", ...] }

To go one step further — which clinicians take that plan — call search_providers with both filters:

{ "state": "OH", "insurance": "Aetna" }

"Who would I be seeing?"

search_providers returns { total, providers } where each provider carries a slug, displayName, credentials, providerType, gender, and bio. Optional filters: state, insurance, providerType (physician / nursePractitioner), gender, plus limit / offset for paging.

For one clinician's full public profile — education, certifications, clinical interests, insurance accepted by state — pass their slug to get_provider:

{ "slug": "barbra-hanna" }

"What kind of visit should I book?"

Call list_appointment_types, optionally scoped by state. Each entry has a numeric id, a name, a patient-friendly description, its modality (video or async), and whether it's newPatientEligible:

{
  "state": "OH",
  "appointmentTypes": [
    { "id": 24, "name": "Annual Well-Woman Visit", "modality": "video", "newPatientEligible": true, ... }
  ]
}

"How soon can I be seen?"

Call check_availability — state is required, and you can narrow by appointmentType (the numeric id from list_appointment_types), a provider slug, horizonDays, or limit:

// arguments
{ "state": "OH", "appointmentType": 24 }

// result
{
  "nextAvailable": "2026-08-04T20:20:00Z",
  "slots": [{ "startTime": "2026-08-04T20:20:00Z", "providerSlug": "liz-hederman" }, ...]
}

Times are UTC (ISO 8601) — convert to the customer's timezone before quoting one.

Chaining tools

Two arguments come from earlier calls rather than from the customer:

slug (for get_provider, check_availability's provider) comes from a search_providers result or an availability slot's providerSlug.
appointmentType (for check_availability) is the numeric id from list_appointment_types.

So the natural flows are search_providers → get_provider and list_appointment_types → check_availability.

Fin makes one connector call per turn

Intercom Fin won't chain two tool calls in a single reply. Broad tools (list_states, list_insurances) usually answer the question outright in one call; multi-step flows resolve naturally across turns as the conversation narrows. For a guaranteed sequence, wire the tools into a Fin Workflow or Procedure instead of relying on auto-invocation.

Answering safely

Everything here is read-only, public data — no patient records, no booking, no side effects, so there's nothing an assistant can break. When a lookup fails (unknown slug, unrecognized filter, upstream hiccup) the tool returns a short plain-language message flagged with isError instead of an error body. Those messages are written to be relayed to an end user verbatim — don't retry on them mechanically; the message says whether the input or the timing was the problem.

Testing by hand

Useful when wiring up a new client and you want to confirm the server — not your client config — is behaving. MCP speaks JSON-RPC over streamable HTTP, so plain curl works:

Initialize

curl -s https://developer.mymenopauserx.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

The server is stateless — no session header comes back, and none is needed on later requests.

List the tools

curl -s https://developer.mymenopauserx.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

You should see exactly six tools.

Call one

curl -s https://developer.mymenopauserx.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_providers","arguments":{"state":"OH","limit":2}}}'

Responses arrive as a server-sent event stream — the JSON-RPC result is in the data: line.

For an interactive session, MCP Inspector works out of the box:

npx @modelcontextprotocol/inspector
# transport: Streamable HTTP, URL: https://developer.mymenopauserx.com/api/mcp

Troubleshooting

/api/sse returns 404 — expected. Only streamable HTTP at /api/mcp is enabled; point older SSE-only clients elsewhere or upgrade them.
Client insists on authentication — there is none. Leave token and OAuth fields blank.
A tool returns a "couldn't look that up" message — that's the friendly error path, safe to show the customer. Check the arguments first (valid state code? real slug?) before assuming an outage.

On this page