Consumer Pricing API

07

MCP serverPublic Preview

Connect your AI agent to quickly get started with the Turquoise Consumer Pricing API and power personalized price estimates in AI-enabled chat experiences.

What is Consumer Pricing MCP?

MCP (Model Context Protocol) is an open standard for connecting AI assistants to external tools and data. Our hosted MCP server exposes Turquoise’s consumer pricing as a small set of tools an assistant can call to find shoppable-service prices, compare providers, estimate what a member will owe under their own benefits, and explain estimates directly in a conversation.

There are two ways to use it:

Exploring

Connect a client

Connect our server to Claude Code, Claude Desktop, Codex, or Cursor and explore our pricing data conversationally.

Quick start
Building

Integrate with your product

Call the MCP from your own agent or backend to power a chat-based healthcare pricing experience for patients.

Integrate

Supported tools

The server offers a set of tools to explore prices and easily surface healthcare pricing to patients from the Consumer Pricing API. Expand a tool for example prompts and the REST endpoints it calls on your behalf:

find_entity Find services, providers, insurance plans, or payers by name, by exact ID, or by how they relate to each other.

Example prompts

“Where can I get a colonoscopy near 80202?”

“I need an ACL repair.”

“Which plans have rates for this at Denver Health?”

API endpoints

  • GET /v3/packages: services, by name or billing code
  • GET /v3/providers: providers, by name, NPI, type, or location
  • GET /v3/networks: insurance plans and networks
  • GET /v3/payers: payers
compare_prices Review price ranges and ranked provider lists for a service in your area. Optionally, compare prices across plans.

Example prompts

“How much is a MRI with contrast near Denver, and who’s cheapest?”

“Compare colonoscopy prices when paying with insurance vs cash in Austin.”

API endpoints

  • POST /v3/prices/compare: the local price distribution
  • POST /v3/prices/query: the ranked provider prices
provider_cost_detail Surface one provider’s price for a service, the components expected to be billed with it, and how it compares locally.

Example prompts

“What would this colonoscopy cost me at Baylor Scott & White?”

“What’s included in that $482 price?”

API endpoints

  • POST /v3/prices/query: find the provider’s price and nearby alternatives
  • GET /v3/prices/{price_id}?expand=line_items: the total plus expected billing components
  • POST /v3/prices/compare: where that price sits in the local market
explain_pricing Contextualize any of our prices or packages to understand how they were derived and how to interpret them.

Example prompts

“Why is this price so high?”

“What does this price include?”

API endpoints

None. Static methodology content, no upstream call.

estimate_out_of_pocket Estimate what a member will personally owe, using their real benefits retrieved through a consented eligibility check. Coming Soon

Example prompts

“What will I owe for a colonoscopy with my Cigna National OAP plan?”

“Have I met my deductible, and what does that mean for this MRI?”

API endpoints

Connect a client

Our server is compatible with any MCP-capable client. Sample clients include Claude Code, Claude Desktop, Codex, and Cursor. You may also elect to add our hosted server to your own agent. Follow the instructions below for your preferred assistant.

Once connected, the endpoint is served over Streamable HTTP with bearer token authentication. If you are also using the Consumer Pricing API, this will be the same credential you use to access the REST API.

Server URL

https://consumer-mcp.turquoise.health/mcp

Sign up for a demo account to get a token, then follow the client setup instructions.


Integrate with your product

Want to integrate personalized healthcare estimates into a patient-facing experience? Build the tools into your own agent or product to power a chat-based pricing experience.

For a production agent or backend, mint a token with the OAuth 2.0 client-credentials flow (the same call as Start Building), then send it as a bearer token on every request to /mcp. Credentials are provisioned automatically. Note that each token must carry the read:mcp scope.

The pricing tools need a payment basis (cash or insurance) and a location before they will return a dollar figure. When something is missing, the tool returns a needs field naming what to ask the patient for, instead of a price.

# 1. Mint an access token (carries read:mcp)
TOKEN=$(curl -s --request POST \
  --url "https://api.turquoise.health/oauth/token" \
  --header "content-type: application/json" \
  --data '{"grant_type":"client_credentials","client_id":"<clientID>","client_secret":"<clientSecret>","organization_id":"<organizationID>"}' \
  | jq -r .access_token)

# 2. Call compare_prices on the MCP endpoint
curl -s --request POST \
  --url "https://consumer-mcp.turquoise.health/mcp" \
  --header "authorization: Bearer $TOKEN" \
  --header "accept: application/json, text/event-stream" \
  --header "content-type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"compare_prices","arguments":{"service":"MRI with contrast","zip_code":"78701","payment":"cash"}}}'
ResponseMeaning
200Auth OK. Token is valid and carries read:mcp.
401Missing, expired, or wrong-audience token.
403Token is valid but not granted read:mcp.

The tools are workflow-shaped rather than one-per-endpoint: each one resolves plain-language names and composes several v3 REST calls server-side. If you would rather orchestrate that yourself, every tool in Supported tools lists the endpoints it calls.