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:
Connect a client
Connect our server to Claude Code, Claude Desktop, Codex, or Cursor and explore our pricing data conversationally.
Quick startIntegrate with your product
Call the MCP from your own agent or backend to power a chat-based healthcare pricing experience for patients.
IntegrateSupported 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 codeGET /v3/providers: providers, by name, NPI, type, or locationGET /v3/networks: insurance plans and networksGET /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 distributionPOST /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 alternativesGET /v3/prices/{price_id}?expand=line_items: the total plus expected billing componentsPOST /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
-
POST /v3/personalized-estimates: eligibility plus member cost share, documented in Personalized Estimates
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"}}}'
import asyncio, httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async def main():
token = httpx.post(
"https://api.turquoise.health/oauth/token",
json={"grant_type": "client_credentials", "client_id": TQ_CLIENT_ID,
"client_secret": TQ_CLIENT_SECRET, "organization_id": TQ_ORG_ID},
).json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}
async with streamablehttp_client(
"https://consumer-mcp.turquoise.health/mcp", headers=headers
) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.call_tool(
"compare_prices",
{"service": "MRI with contrast", "zip_code": "78701", "payment": "cash"},
)
print(result)
asyncio.run(main())
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const res = await fetch("https://api.turquoise.health/oauth/token", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
grant_type: "client_credentials",
client_id: process.env.TQ_CLIENT_ID,
client_secret: process.env.TQ_CLIENT_SECRET,
organization_id: process.env.TQ_ORG_ID,
}),
});
const { access_token } = await res.json();
const transport = new StreamableHTTPClientTransport(
new URL("https://consumer-mcp.turquoise.health/mcp"),
{ requestInit: { headers: { Authorization: `Bearer ${access_token}` } } },
);
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);
const result = await client.callTool({
name: "compare_prices",
arguments: { service: "MRI with contrast", zip_code: "78701", payment: "cash" },
});
console.log(result);
| Response | Meaning |
|---|---|
200 | Auth OK. Token is valid and carries read:mcp. |
401 | Missing, expired, or wrong-audience token. |
403 | Token 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.