Verity MCP Server

Instructions

Implementation Reference

• src/index.ts:289-362 (registration)

  Registration of the 'search_policies' MCP tool, including description, input schema using Zod, and inline async handler function that queries the Verity API /policies endpoint and formats results.
  server.registerTool( "search_policies", { description: `Search Medicare coverage policies (LCDs, NCDs, Articles). Use this to find policies related to procedures, conditions, or coverage questions. Supports keyword and semantic search modes. Examples: - search_policies("ultrasound guidance") - find policies about ultrasound - search_policies("diabetes CGM") - find continuous glucose monitor policies - search_policies("", { policy_type: "NCD" }) - list all National Coverage Determinations`, inputSchema: { query: z.string().max(500).optional().describe("Search query - leave empty to browse"), mode: z.enum(["keyword", "semantic"]).default("keyword").describe("Search mode: keyword (exact) or semantic (conceptual)"), policy_type: z .enum(["LCD", "Article", "NCD", "PayerPolicy", "Medical Policy", "Drug Policy"]) .optional() .describe("Filter by policy type"), jurisdiction: z.string().max(10).optional().describe("MAC jurisdiction code (e.g., JM, JH, JK)"), payer: z.string().max(50).optional().describe("Filter by payer name"), status: z.enum(["active", "retired", "all"]).default("active").describe("Policy status filter"), limit: z.number().min(1).max(100).default(20).describe("Results per page"), cursor: z.string().optional().describe("Pagination cursor from previous response"), include: z.string().optional().describe("Additional data: 'summary', 'criteria', 'codes'"), }, }, async ({ query, mode, policy_type, jurisdiction, payer, status, limit, cursor, include }) => { try { const result = await verityRequest<any>("/policies", { params: { q: query, mode, policy_type, jurisdiction, payer, status, limit, cursor, include, }, }); if (!result.data || result.data.length === 0) { return { content: [ { type: "text", text: `No policies found for "${query || "your search"}". Try:\n- Broader search terms\n- Different policy type\n- Remove jurisdiction filter`, }, ], }; } const lines: string[] = [`Found ${result.data.length} policies${result.meta?.pagination?.has_more ? " (more available)" : ""}:\n`]; result.data.forEach((policy: any, i: number) => { lines.push(`${i + 1}. ${formatPolicy(policy)}`); lines.push(""); }); if (result.meta?.pagination?.cursor) { lines.push(`\nMore results available. Use cursor: "${result.meta.pagination.cursor}"`); } return { content: [{ type: "text", text: lines.join("\n") }], }; } catch (error) { return { content: [{ type: "text", text: `Error searching policies: ${error instanceof Error ? error.message : String(error)}` }], }; } } );
• src/index.ts:315-361 (handler)

  Handler function for search_policies tool: destructures input params, calls verityRequest('/policies') with query parameters, handles empty results or errors, formats policy list using formatPolicy, and returns markdown-formatted text content.
  async ({ query, mode, policy_type, jurisdiction, payer, status, limit, cursor, include }) => { try { const result = await verityRequest<any>("/policies", { params: { q: query, mode, policy_type, jurisdiction, payer, status, limit, cursor, include, }, }); if (!result.data || result.data.length === 0) { return { content: [ { type: "text", text: `No policies found for "${query || "your search"}". Try:\n- Broader search terms\n- Different policy type\n- Remove jurisdiction filter`, }, ], }; } const lines: string[] = [`Found ${result.data.length} policies${result.meta?.pagination?.has_more ? " (more available)" : ""}:\n`]; result.data.forEach((policy: any, i: number) => { lines.push(`${i + 1}. ${formatPolicy(policy)}`); lines.push(""); }); if (result.meta?.pagination?.cursor) { lines.push(`\nMore results available. Use cursor: "${result.meta.pagination.cursor}"`); } return { content: [{ type: "text", text: lines.join("\n") }], }; } catch (error) { return { content: [{ type: "text", text: `Error searching policies: ${error instanceof Error ? error.message : String(error)}` }], }; } }
• src/index.ts:300-313 (schema)

  Zod inputSchema for validating parameters of the search_policies tool: query, mode, policy_type, jurisdiction, payer, status, limit, cursor, include.
  inputSchema: { query: z.string().max(500).optional().describe("Search query - leave empty to browse"), mode: z.enum(["keyword", "semantic"]).default("keyword").describe("Search mode: keyword (exact) or semantic (conceptual)"), policy_type: z .enum(["LCD", "Article", "NCD", "PayerPolicy", "Medical Policy", "Drug Policy"]) .optional() .describe("Filter by policy type"), jurisdiction: z.string().max(10).optional().describe("MAC jurisdiction code (e.g., JM, JH, JK)"), payer: z.string().max(50).optional().describe("Filter by payer name"), status: z.enum(["active", "retired", "all"]).default("active").describe("Policy status filter"), limit: z.number().min(1).max(100).default(20).describe("Results per page"), cursor: z.string().optional().describe("Pagination cursor from previous response"), include: z.string().optional().describe("Additional data: 'summary', 'criteria', 'codes'"), },
• src/index.ts:107-163 (helper)

  formatPolicy helper function used by the search_policies handler to format policy data into readable markdown text, supporting detailed mode.
  function formatPolicy(policy: any, detailed = false): string { const lines: string[] = []; lines.push(`Policy: ${policy.policy_id} - ${policy.title}`); lines.push(`Type: ${policy.policy_type} | Status: ${policy.status}`); if (policy.jurisdiction) lines.push(`Jurisdiction: ${policy.jurisdiction}`); if (policy.effective_date) lines.push(`Effective: ${policy.effective_date}`); if (policy.retire_date) lines.push(`Retired: ${policy.retire_date}`); if (detailed) { if (policy.description) lines.push(`\nDescription: ${policy.description}`); if (policy.summary) lines.push(`\nSummary: ${policy.summary}`); if (policy.mac) { lines.push(`\nMAC: ${policy.mac.name} (${policy.mac.jurisdiction_name})`); if (policy.mac.states) lines.push(`States: ${policy.mac.states.join(", ")}`); } if (policy.sections) { if (policy.sections.indications) { lines.push(`\n--- Indications ---\n${policy.sections.indications.slice(0, 1000)}${policy.sections.indications.length > 1000 ? "..." : ""}`); } if (policy.sections.limitations) { lines.push(`\n--- Limitations ---\n${policy.sections.limitations.slice(0, 1000)}${policy.sections.limitations.length > 1000 ? "..." : ""}`); } if (policy.sections.documentation) { lines.push(`\n--- Documentation Requirements ---\n${policy.sections.documentation.slice(0, 1000)}${policy.sections.documentation.length > 1000 ? "..." : ""}`); } } if (policy.criteria && Object.keys(policy.criteria).length > 0) { lines.push("\n--- Coverage Criteria ---"); Object.entries(policy.criteria).forEach(([section, blocks]: [string, any]) => { lines.push(`\n[${section.toUpperCase()}]`); blocks.slice(0, 3).forEach((block: any) => { lines.push(` - ${block.text.slice(0, 200)}${block.text.length > 200 ? "..." : ""}`); if (block.tags?.length) lines.push(` Tags: ${block.tags.join(", ")}`); }); if (blocks.length > 3) lines.push(` ... and ${blocks.length - 3} more criteria`); }); } if (policy.codes && Object.keys(policy.codes).length > 0) { lines.push("\n--- Associated Codes ---"); Object.entries(policy.codes).forEach(([system, codes]: [string, any]) => { lines.push(`\n[${system}] (${codes.length} codes)`); codes.slice(0, 10).forEach((c: any) => { lines.push(` - ${c.code}: ${c.display || "No description"} [${c.disposition}]`); }); if (codes.length > 10) lines.push(` ... and ${codes.length - 10} more codes`); }); } } if (policy.source_url) lines.push(`\nSource: ${policy.source_url}`); return lines.join("\n"); }
• src/index.ts:25-66 (helper)

  verityRequest helper function used by all tools including search_policies to make authenticated API requests to the Verity API backend.
  async function verityRequest<T>( endpoint: string, options: { method?: "GET" | "POST"; params?: Record<string, string | number | boolean | undefined>; body?: unknown; } = {} ): Promise<T> { const { method = "GET", params, body } = options; // Build URL with query params const url = new URL(`${VERITY_API_BASE}${endpoint}`); if (params) { Object.entries(params).forEach(([key, value]) => { if (value !== undefined && value !== null && value !== "") { url.searchParams.append(key, String(value)); } }); } const headers: Record<string, string> = { Authorization: `Bearer ${VERITY_API_KEY}`, "Content-Type": "application/json", Accept: "application/json", }; const response = await fetch(url.toString(), { method, headers, body: body ? JSON.stringify(body) : undefined, }); const data = await response.json(); if (!response.ok) { const errorMsg = data.error?.message || `API error: ${response.status}`; const hint = data.error?.hint || ""; throw new Error(hint ? `${errorMsg}. Hint: ${hint}` : errorMsg); } return data as T; }