# 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](#connect-a-client) 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](#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 * `POST /v3/personalized-estimates`: eligibility plus member cost share, documented in [Personalized Estimates](/api/docs/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](/signup/?signupContext=api) 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](/api/docs/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. **cURL** ``` # 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":"","client_secret":"","organization_id":""}' \ | 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"}}}' ``` **Python** ``` 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()) ``` **TypeScript** ``` 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](#supported-tools) lists the endpoints it calls.