[{"data":1,"prerenderedAt":1391},["ShallowReactive",2],{"series-\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fsearching-openapi-specification-without-filling-the-context":3,"series-context-\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers":1201},{"id":4,"title":5,"body":6,"contentId":1186,"date":1187,"description":1188,"extension":1189,"github":1190,"meetTheInstructor":1192,"meta":1193,"navigation":410,"part":79,"path":1194,"rawbody":1195,"robots":1192,"schemaOrg":1192,"seo":1196,"seriesSlug":1197,"sitemap":1198,"stem":1199,"subtitle":1192,"topics":1192,"__hash__":1200},"series\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fsearching-openapi-specification-without-filling-the-context.md","Searching OpenAPI Specifications Without Filling Context",{"type":7,"value":8,"toc":1179},"minimark",[9,13,16,21,32,40,260,267,270,290,293,296,299,303,306,309,320,328,331,342,345,349,352,355,358,367,370,576,579,582,585,589,592,846,849,852,858,861,864,1111,1114,1121,1124,1130,1133,1150,1153,1156,1160,1163,1175],[10,11,12],"p",{},"In the previous article, we learned what Code Mode is and how useful it can be to let the model write orchestration code instead of calling tools directly.",[10,14,15],{},"In this third part of the series, we will explore how we can use Code Mode when the context window is limited or when we have a document—an OpenAPI specification in our case—that is larger than the context window.",[17,18,20],"h2",{"id":19},"the-context-window-problem","The context window problem",[10,22,23,24,31],{},"When developing a service or an application, we often build an API to allow other services to interact with our system. Developers traditionally learn how to use that API through documentation websites, such as the ",[25,26,30],"a",{"href":27,"rel":28},"https:\u002F\u002Fdevelopers.cloudflare.com\u002Fapi\u002F",[29],"nofollow","Cloudflare API reference",".",[10,33,34,35,31],{},"To make those websites easier to build, maintain, and keep in sync with the actual API, the industry created a specification format: ",[25,36,39],{"href":37,"rel":38},"https:\u002F\u002Fswagger.io\u002Fspecification\u002F",[29],"OpenAPI",[41,42,48],"pre",{"className":43,"code":44,"filename":45,"language":46,"meta":47,"style":47},"language-yaml shiki shiki-themes github-light github-light github-dark","openapi: 3.0.0\ninfo:\n  title: Sample API\n  version: 1.0.0\npaths:\n  \u002Fusers:\n    get:\n      summary: Get all users\n      responses:\n        '200':\n          description: A list of users\n          content:\n            application\u002Fjson:\n              schema:\n                type: array\n                items:\n                  type: object\n                  properties:\n                    id:\n                      type: string\n                    name:\n                      type: string\n","Example","yaml","",[49,50,51,68,77,89,100,108,116,124,135,143,151,162,170,178,186,197,205,216,224,232,243,251],"code",{"__ignoreMap":47},[52,53,56,60,64],"span",{"class":54,"line":55},"line",1,[52,57,59],{"class":58},"sovSZ","openapi",[52,61,63],{"class":62},"sxrX7",": ",[52,65,67],{"class":66},"sBjJW","3.0.0\n",[52,69,71,74],{"class":54,"line":70},2,[52,72,73],{"class":58},"info",[52,75,76],{"class":62},":\n",[52,78,80,83,85],{"class":54,"line":79},3,[52,81,82],{"class":58},"  title",[52,84,63],{"class":62},[52,86,88],{"class":87},"sIIMD","Sample API\n",[52,90,92,95,97],{"class":54,"line":91},4,[52,93,94],{"class":58},"  version",[52,96,63],{"class":62},[52,98,99],{"class":66},"1.0.0\n",[52,101,103,106],{"class":54,"line":102},5,[52,104,105],{"class":58},"paths",[52,107,76],{"class":62},[52,109,111,114],{"class":54,"line":110},6,[52,112,113],{"class":58},"  \u002Fusers",[52,115,76],{"class":62},[52,117,119,122],{"class":54,"line":118},7,[52,120,121],{"class":58},"    get",[52,123,76],{"class":62},[52,125,127,130,132],{"class":54,"line":126},8,[52,128,129],{"class":58},"      summary",[52,131,63],{"class":62},[52,133,134],{"class":87},"Get all users\n",[52,136,138,141],{"class":54,"line":137},9,[52,139,140],{"class":58},"      responses",[52,142,76],{"class":62},[52,144,146,149],{"class":54,"line":145},10,[52,147,148],{"class":87},"        '200'",[52,150,76],{"class":62},[52,152,154,157,159],{"class":54,"line":153},11,[52,155,156],{"class":58},"          description",[52,158,63],{"class":62},[52,160,161],{"class":87},"A list of users\n",[52,163,165,168],{"class":54,"line":164},12,[52,166,167],{"class":58},"          content",[52,169,76],{"class":62},[52,171,173,176],{"class":54,"line":172},13,[52,174,175],{"class":58},"            application\u002Fjson",[52,177,76],{"class":62},[52,179,181,184],{"class":54,"line":180},14,[52,182,183],{"class":58},"              schema",[52,185,76],{"class":62},[52,187,189,192,194],{"class":54,"line":188},15,[52,190,191],{"class":58},"                type",[52,193,63],{"class":62},[52,195,196],{"class":87},"array\n",[52,198,200,203],{"class":54,"line":199},16,[52,201,202],{"class":58},"                items",[52,204,76],{"class":62},[52,206,208,211,213],{"class":54,"line":207},17,[52,209,210],{"class":58},"                  type",[52,212,63],{"class":62},[52,214,215],{"class":87},"object\n",[52,217,219,222],{"class":54,"line":218},18,[52,220,221],{"class":58},"                  properties",[52,223,76],{"class":62},[52,225,227,230],{"class":54,"line":226},19,[52,228,229],{"class":58},"                    id",[52,231,76],{"class":62},[52,233,235,238,240],{"class":54,"line":234},20,[52,236,237],{"class":58},"                      type",[52,239,63],{"class":62},[52,241,242],{"class":87},"string\n",[52,244,246,249],{"class":54,"line":245},21,[52,247,248],{"class":58},"                    name",[52,250,76],{"class":62},[52,252,254,256,258],{"class":54,"line":253},22,[52,255,237],{"class":58},[52,257,63],{"class":62},[52,259,242],{"class":87},[10,261,262,263,266],{},"This example shows a simple OpenAPI specification for an API that has a single endpoint ",[49,264,265],{},"\u002Fusers"," which returns a list of users. The specification describes the endpoint, the HTTP method, the expected response, and the data format.",[10,268,269],{},"This is powerful for programmatic use and can generate useful human-facing documentation. However, a large raw specification is difficult to navigate manually and can exceed a model's context window. In those cases, we cannot simply provide the complete document to the model and expect it to use it effectively.",[271,272,273,282],"ul",{},[274,275,276,281],"li",{},[25,277,280],{"href":278,"rel":279},"https:\u002F\u002Fgithub.com\u002Fgithub\u002Frest-api-description\u002Fblob\u002Fmain\u002Fdescriptions\u002Fghes-3.21\u002Fghes-3.21.json",[29],"GitHub's GHES 3.21 OpenAPI specification"," is 11.1 MB.",[274,283,284,289],{},[25,285,288],{"href":286,"rel":287},"https:\u002F\u002Fgithub.com\u002Fcloudflare\u002Fapi-schemas\u002Fblob\u002Fmain\u002Fopenapi.json",[29],"Cloudflare's OpenAPI specification"," is 22.7 MB.",[10,291,292],{},"These files evolve, so their exact sizes will change. The point is that real API descriptions can be far larger than the information needed for a single task.",[10,294,295],{},"The Cloudflare snapshot used in this series contains 23,792,523 characters. The rough shortcut of four characters per token suggests about 6 million tokens, but tokenization varies by model and content. Either way, it is much larger than many available context windows.",[10,297,298],{},"We cannot simply provide the entire specification to the model.",[17,300,302],{"id":301},"openapi-specifications-are-for-people-and-machines","OpenAPI specifications are for people and machines",[10,304,305],{},"OpenAPI is designed to let both people and software understand an API. A documentation generator can turn it into a website; a client generator can turn it into code. For a model, however, returning the complete specification as context is still usually the wrong interface. The model needs the relevant endpoints and schemas for the task, not every operation in the API.",[10,307,308],{},"However, nothing prevents us from building a tool that can search the OpenAPI specification and return only the relevant information. Imagine, you're trying to integrate a marketplace platform and you want to know how to create a return.",[10,310,311,312,315,316,319],{},"Instead of using ",[49,313,314],{},"Ctrl+F"," or ",[49,317,318],{},"Cmd+F"," on the OpenAPI specification, why couldn't we use this algorithm to search it?",[41,321,326],{"className":322,"code":324,"filename":45,"language":325,"meta":47},[323],"language-text","searchTerm = \"return\"\nresults = []\n\nfor each URL path and path item in spec.paths:\n    for each HTTP method and operation in the path item:\n        if the entry is not an HTTP operation:\n            continue\n\n        searchableText = combine:\n            - the URL path\n            - the operation ID\n            - the summary\n            - the description\n            - the operation tags\n\n        if searchableText does not contain searchTerm:\n            continue\n\n        endpoint = {\n            method: the HTTP method in uppercase,\n            path: the URL path,\n            operationId: the operation ID,\n            summary: the operation summary,\n            parameters: [\n                for each parameter:\n                    keep its name, location, and required flag\n            ],\n            requestBody: keep only its content types and required flag,\n            responses: [\n                for each response:\n                    keep its status code and description\n            ]\n        }\n\n        add endpoint to results\n\nreturn results\n","text",[49,327,324],{"__ignoreMap":47},[10,329,330],{},"That way, we extract only the relevant information. But we can go even further.",[10,332,333,334,337,338,341],{},"For now, even with an algorithm like this, we still have to run the code manually and there is no way of knowing if our algorithm will handle all the cases. For example, to create a return, we could filter the results to only keep the endpoints that have a ",[49,335,336],{},"POST"," method. Maybe filtering using tags is better than trying to guess the right wording to use in the search term in summary and description. We could also filter the results to only keep the endpoints that have a ",[49,339,340],{},"200"," response code. There are so many different ways to filter the results, depending on the client, the data we need, and the task we want to perform, that writing a generic algorithm is far too complex.",[10,343,344],{},"We need to write a custom algorithm for each use case.",[17,346,348],{"id":347},"llms-know-code-and-algorithms","LLMs know code and algorithms",[10,350,351],{},"Or we can delegate this task to a LLM.",[10,353,354],{},"One practical strength of LLMs is generating code. They can turn a task-specific request into a small search program that developers can review and execute.",[10,356,357],{},"So, instead of writing a generic algorithm—or thousands of them to try to cover all the cases—we could just ask the LLM to write the algorithm for us. Then, we just have to execute it. That way, the LLM gets exactly the information it needs, and we do not have to worry about the context window problem.",[10,359,360,361,366],{},"The first time I heard about this idea was in a Cloudflare blog post named ",[25,362,365],{"href":363,"rel":364},"https:\u002F\u002Fblog.cloudflare.com\u002Fcode-mode\u002F",[29],"Code Mode"," and I was \"what?\". I honestly had to read it more than twice to understand what it was about. Let me give you an example.",[10,368,369],{},"Imagine you want to create a return on a marketplace platform. Instead of giving the entire OpenAPI specification to the model, you could write the following method:",[41,371,375],{"className":372,"code":373,"filename":45,"language":374,"meta":47,"style":47},"language-js shiki shiki-themes github-light github-light github-dark","async () => {\n  const results = []\n\n  for (const [path, methods] of Object.entries(spec.paths)) {\n    const operation = methods.post\n\n    if (operation?.tags?.some(tag => tag.toLowerCase() === 'returns')) {\n      results.push({\n        method: 'POST',\n        path,\n        summary: operation.summary,\n        requestBody: operation.requestBody\n      })\n    }\n  }\n\n  return results\n}\n","js",[49,376,377,392,406,412,451,464,468,507,518,529,534,539,544,549,554,559,563,571],{"__ignoreMap":47},[52,378,379,383,386,389],{"class":54,"line":55},[52,380,382],{"class":381},"s8jYJ","async",[52,384,385],{"class":62}," () ",[52,387,388],{"class":381},"=>",[52,390,391],{"class":62}," {\n",[52,393,394,397,400,403],{"class":54,"line":70},[52,395,396],{"class":381},"  const",[52,398,399],{"class":66}," results",[52,401,402],{"class":381}," =",[52,404,405],{"class":62}," []\n",[52,407,408],{"class":54,"line":79},[52,409,411],{"emptyLinePlaceholder":410},true,"\n",[52,413,414,417,420,423,426,429,432,435,438,441,444,448],{"class":54,"line":91},[52,415,416],{"class":381},"  for",[52,418,419],{"class":62}," (",[52,421,422],{"class":381},"const",[52,424,425],{"class":62}," [",[52,427,428],{"class":66},"path",[52,430,431],{"class":62},", ",[52,433,434],{"class":66},"methods",[52,436,437],{"class":62},"] ",[52,439,440],{"class":381},"of",[52,442,443],{"class":62}," Object.",[52,445,447],{"class":446},"snPdu","entries",[52,449,450],{"class":62},"(spec.paths)) {\n",[52,452,453,456,459,461],{"class":54,"line":102},[52,454,455],{"class":381},"    const",[52,457,458],{"class":66}," operation",[52,460,402],{"class":381},[52,462,463],{"class":62}," methods.post\n",[52,465,466],{"class":54,"line":110},[52,467,411],{"emptyLinePlaceholder":410},[52,469,470,473,476,479,482,486,489,492,495,498,501,504],{"class":54,"line":118},[52,471,472],{"class":381},"    if",[52,474,475],{"class":62}," (operation?.tags?.",[52,477,478],{"class":446},"some",[52,480,481],{"class":62},"(",[52,483,485],{"class":484},"sP4rz","tag",[52,487,488],{"class":381}," =>",[52,490,491],{"class":62}," tag.",[52,493,494],{"class":446},"toLowerCase",[52,496,497],{"class":62},"() ",[52,499,500],{"class":381},"===",[52,502,503],{"class":87}," 'returns'",[52,505,506],{"class":62},")) {\n",[52,508,509,512,515],{"class":54,"line":126},[52,510,511],{"class":62},"      results.",[52,513,514],{"class":446},"push",[52,516,517],{"class":62},"({\n",[52,519,520,523,526],{"class":54,"line":137},[52,521,522],{"class":62},"        method: ",[52,524,525],{"class":87},"'POST'",[52,527,528],{"class":62},",\n",[52,530,531],{"class":54,"line":145},[52,532,533],{"class":62},"        path,\n",[52,535,536],{"class":54,"line":153},[52,537,538],{"class":62},"        summary: operation.summary,\n",[52,540,541],{"class":54,"line":164},[52,542,543],{"class":62},"        requestBody: operation.requestBody\n",[52,545,546],{"class":54,"line":172},[52,547,548],{"class":62},"      })\n",[52,550,551],{"class":54,"line":180},[52,552,553],{"class":62},"    }\n",[52,555,556],{"class":54,"line":188},[52,557,558],{"class":62},"  }\n",[52,560,561],{"class":54,"line":199},[52,562,411],{"emptyLinePlaceholder":410},[52,564,565,568],{"class":54,"line":207},[52,566,567],{"class":381},"  return",[52,569,570],{"class":62}," results\n",[52,572,573],{"class":54,"line":218},[52,574,575],{"class":62},"}\n",[10,577,578],{},"With the code above, we can quickly search the OpenAPI specification and return only the relevant information.",[10,580,581],{},"But who wants to write this code? Nobody.",[10,583,584],{},"Fortunately, LLMs can generate this code for us. Give them access to the OpenAPI specification and a couple of examples, and LLMs can search the entire specification to find only what is relevant.",[17,586,588],{"id":587},"tool-description-and-language","Tool, description and language",[10,590,591],{},"In our MCP, the search tool would look like this:",[41,593,598],{"className":594,"code":595,"filename":596,"language":597,"meta":47,"style":47},"language-typescript shiki shiki-themes github-light github-light github-dark","server.registerTool(\n  'search',\n  {\n    title: 'Search OpenAPI Specification',\n    description: '...',\n    inputSchema: z.object({\n      code: z\n        .string()\n        .max(MAX_CODE_LENGTH)\n        .describe('An async arrow function that searches the OpenAPI spec')\n    }),\n  },\n  async ({ code }) => {\n    try {\n      const result = await evaluateSearchCode(code)\n      return { content: [{ type: 'text', text: formatSearchResult(result) }] }\n    }\n    catch (error) {\n      return {\n        content: [{ type: 'text', text: `Search failed: ${errorMessage(error)}` }],\n        isError: true\n      }\n    }\n  }\n)\n","search.ts","typescript",[49,599,600,611,618,623,633,643,653,658,669,684,698,703,708,725,732,751,771,775,783,789,818,826,831,836,841],{"__ignoreMap":47},[52,601,602,605,608],{"class":54,"line":55},[52,603,604],{"class":62},"server.",[52,606,607],{"class":446},"registerTool",[52,609,610],{"class":62},"(\n",[52,612,613,616],{"class":54,"line":70},[52,614,615],{"class":87},"  'search'",[52,617,528],{"class":62},[52,619,620],{"class":54,"line":79},[52,621,622],{"class":62},"  {\n",[52,624,625,628,631],{"class":54,"line":91},[52,626,627],{"class":62},"    title: ",[52,629,630],{"class":87},"'Search OpenAPI Specification'",[52,632,528],{"class":62},[52,634,635,638,641],{"class":54,"line":102},[52,636,637],{"class":62},"    description: ",[52,639,640],{"class":87},"'...'",[52,642,528],{"class":62},[52,644,645,648,651],{"class":54,"line":110},[52,646,647],{"class":62},"    inputSchema: z.",[52,649,650],{"class":446},"object",[52,652,517],{"class":62},[52,654,655],{"class":54,"line":118},[52,656,657],{"class":62},"      code: z\n",[52,659,660,663,666],{"class":54,"line":126},[52,661,662],{"class":62},"        .",[52,664,665],{"class":446},"string",[52,667,668],{"class":62},"()\n",[52,670,671,673,676,678,681],{"class":54,"line":137},[52,672,662],{"class":62},[52,674,675],{"class":446},"max",[52,677,481],{"class":62},[52,679,680],{"class":66},"MAX_CODE_LENGTH",[52,682,683],{"class":62},")\n",[52,685,686,688,691,693,696],{"class":54,"line":145},[52,687,662],{"class":62},[52,689,690],{"class":446},"describe",[52,692,481],{"class":62},[52,694,695],{"class":87},"'An async arrow function that searches the OpenAPI spec'",[52,697,683],{"class":62},[52,699,700],{"class":54,"line":153},[52,701,702],{"class":62},"    }),\n",[52,704,705],{"class":54,"line":164},[52,706,707],{"class":62},"  },\n",[52,709,710,713,716,718,721,723],{"class":54,"line":172},[52,711,712],{"class":381},"  async",[52,714,715],{"class":62}," ({ ",[52,717,49],{"class":484},[52,719,720],{"class":62}," }) ",[52,722,388],{"class":381},[52,724,391],{"class":62},[52,726,727,730],{"class":54,"line":180},[52,728,729],{"class":381},"    try",[52,731,391],{"class":62},[52,733,734,737,740,742,745,748],{"class":54,"line":188},[52,735,736],{"class":381},"      const",[52,738,739],{"class":66}," result",[52,741,402],{"class":381},[52,743,744],{"class":381}," await",[52,746,747],{"class":446}," evaluateSearchCode",[52,749,750],{"class":62},"(code)\n",[52,752,753,756,759,762,765,768],{"class":54,"line":199},[52,754,755],{"class":381},"      return",[52,757,758],{"class":62}," { content: [{ type: ",[52,760,761],{"class":87},"'text'",[52,763,764],{"class":62},", text: ",[52,766,767],{"class":446},"formatSearchResult",[52,769,770],{"class":62},"(result) }] }\n",[52,772,773],{"class":54,"line":207},[52,774,553],{"class":62},[52,776,777,780],{"class":54,"line":218},[52,778,779],{"class":381},"    catch",[52,781,782],{"class":62}," (error) {\n",[52,784,785,787],{"class":54,"line":226},[52,786,755],{"class":381},[52,788,391],{"class":62},[52,790,791,794,796,798,801,804,806,809,812,815],{"class":54,"line":234},[52,792,793],{"class":62},"        content: [{ type: ",[52,795,761],{"class":87},[52,797,764],{"class":62},[52,799,800],{"class":87},"`Search failed: ${",[52,802,803],{"class":446},"errorMessage",[52,805,481],{"class":87},[52,807,808],{"class":62},"error",[52,810,811],{"class":87},")",[52,813,814],{"class":87},"}`",[52,816,817],{"class":62}," }],\n",[52,819,820,823],{"class":54,"line":245},[52,821,822],{"class":62},"        isError: ",[52,824,825],{"class":66},"true\n",[52,827,828],{"class":54,"line":253},[52,829,830],{"class":62},"      }\n",[52,832,834],{"class":54,"line":833},23,[52,835,553],{"class":62},[52,837,839],{"class":54,"line":838},24,[52,840,558],{"class":62},[52,842,844],{"class":54,"line":843},25,[52,845,683],{"class":62},[10,847,848],{},"From a high-level perspective, there is nothing more than what we have already seen in the previous article. The details are in the description and the evaluation function.",[10,850,851],{},"The description starts like any other tool description: what is the tool about, and what can the model do with it?",[41,853,856],{"className":854,"code":855,"filename":45,"language":325,"meta":47},[323],"Search the MarketHub OpenAPI specification with JavaScript.\n\nThe specification stays inside the server. Your code must be an async arrow function and should return only the small result needed for the next decision. All local $refs are resolved before the code runs.\n",[49,857,855],{"__ignoreMap":47},[10,859,860],{},"Then, things start to get interesting.",[10,862,863],{},"We can provide TypeScript interfaces to give the model a typed facade against which to write code. This compact contract improves the chance that the model writes a working program on its first attempt.",[41,865,867],{"className":594,"code":866,"filename":45,"language":597,"meta":47,"style":47},"interface OperationInfo {\n  operationId?: string\n  summary?: string\n  description?: string\n  tags?: string[]\n  parameters?: Array\u003C{\n    name?: string\n    in?: string\n    required?: boolean\n    description?: string\n    schema?: unknown\n  }>\n  requestBody?: unknown\n  responses?: Record\u003Cstring, unknown>\n}\n\ndeclare const spec: {\n  paths: Record\u003Cstring, {\n    get?: OperationInfo\n    post?: OperationInfo\n    put?: OperationInfo\n    patch?: OperationInfo\n    delete?: OperationInfo\n  }>\n}\n",[49,868,869,879,890,899,908,921,934,943,952,962,971,981,986,995,1018,1022,1026,1042,1058,1067,1076,1085,1094,1103,1107],{"__ignoreMap":47},[52,870,871,874,877],{"class":54,"line":55},[52,872,873],{"class":381},"interface",[52,875,876],{"class":446}," OperationInfo",[52,878,391],{"class":62},[52,880,881,884,887],{"class":54,"line":70},[52,882,883],{"class":484},"  operationId",[52,885,886],{"class":381},"?:",[52,888,889],{"class":66}," string\n",[52,891,892,895,897],{"class":54,"line":79},[52,893,894],{"class":484},"  summary",[52,896,886],{"class":381},[52,898,889],{"class":66},[52,900,901,904,906],{"class":54,"line":91},[52,902,903],{"class":484},"  description",[52,905,886],{"class":381},[52,907,889],{"class":66},[52,909,910,913,915,918],{"class":54,"line":102},[52,911,912],{"class":484},"  tags",[52,914,886],{"class":381},[52,916,917],{"class":66}," string",[52,919,920],{"class":62},"[]\n",[52,922,923,926,928,931],{"class":54,"line":110},[52,924,925],{"class":484},"  parameters",[52,927,886],{"class":381},[52,929,930],{"class":446}," Array",[52,932,933],{"class":62},"\u003C{\n",[52,935,936,939,941],{"class":54,"line":118},[52,937,938],{"class":484},"    name",[52,940,886],{"class":381},[52,942,889],{"class":66},[52,944,945,948,950],{"class":54,"line":126},[52,946,947],{"class":484},"    in",[52,949,886],{"class":381},[52,951,889],{"class":66},[52,953,954,957,959],{"class":54,"line":137},[52,955,956],{"class":484},"    required",[52,958,886],{"class":381},[52,960,961],{"class":66}," boolean\n",[52,963,964,967,969],{"class":54,"line":145},[52,965,966],{"class":484},"    description",[52,968,886],{"class":381},[52,970,889],{"class":66},[52,972,973,976,978],{"class":54,"line":153},[52,974,975],{"class":484},"    schema",[52,977,886],{"class":381},[52,979,980],{"class":66}," unknown\n",[52,982,983],{"class":54,"line":164},[52,984,985],{"class":62},"  }>\n",[52,987,988,991,993],{"class":54,"line":172},[52,989,990],{"class":484},"  requestBody",[52,992,886],{"class":381},[52,994,980],{"class":66},[52,996,997,1000,1002,1005,1008,1010,1012,1015],{"class":54,"line":180},[52,998,999],{"class":484},"  responses",[52,1001,886],{"class":381},[52,1003,1004],{"class":446}," Record",[52,1006,1007],{"class":62},"\u003C",[52,1009,665],{"class":66},[52,1011,431],{"class":62},[52,1013,1014],{"class":66},"unknown",[52,1016,1017],{"class":62},">\n",[52,1019,1020],{"class":54,"line":188},[52,1021,575],{"class":62},[52,1023,1024],{"class":54,"line":199},[52,1025,411],{"emptyLinePlaceholder":410},[52,1027,1028,1031,1034,1037,1040],{"class":54,"line":207},[52,1029,1030],{"class":381},"declare",[52,1032,1033],{"class":381}," const",[52,1035,1036],{"class":66}," spec",[52,1038,1039],{"class":381},":",[52,1041,391],{"class":62},[52,1043,1044,1047,1049,1051,1053,1055],{"class":54,"line":218},[52,1045,1046],{"class":484},"  paths",[52,1048,1039],{"class":381},[52,1050,1004],{"class":446},[52,1052,1007],{"class":62},[52,1054,665],{"class":66},[52,1056,1057],{"class":62},", {\n",[52,1059,1060,1062,1064],{"class":54,"line":226},[52,1061,121],{"class":484},[52,1063,886],{"class":381},[52,1065,1066],{"class":446}," OperationInfo\n",[52,1068,1069,1072,1074],{"class":54,"line":234},[52,1070,1071],{"class":484},"    post",[52,1073,886],{"class":381},[52,1075,1066],{"class":446},[52,1077,1078,1081,1083],{"class":54,"line":245},[52,1079,1080],{"class":484},"    put",[52,1082,886],{"class":381},[52,1084,1066],{"class":446},[52,1086,1087,1090,1092],{"class":54,"line":253},[52,1088,1089],{"class":484},"    patch",[52,1091,886],{"class":381},[52,1093,1066],{"class":446},[52,1095,1096,1099,1101],{"class":54,"line":833},[52,1097,1098],{"class":484},"    delete",[52,1100,886],{"class":381},[52,1102,1066],{"class":446},[52,1104,1105],{"class":54,"line":838},[52,1106,985],{"class":62},[52,1108,1109],{"class":54,"line":843},[52,1110,575],{"class":62},[10,1112,1113],{},"The full OpenAPI specification stays on the server. The generated program can inspect it through this facade, while the model receives only the compact interface and the final search result.",[1115,1116,1118],"callout",{"color":73,"icon":1117},"i-ph-info-duotone",[10,1119,1120],{},"The OpenAPI specification is simplified in the MCP to make it more AI-friendly.",[10,1122,1123],{},"And finally, here are a couple of examples to show the model how to use the tool and what is expected as a result.",[41,1125,1128],{"className":1126,"code":1127,"filename":45,"language":325,"meta":47},[323],"\u002F\u002F Inspect one operation's request body\nasync () => spec.paths['\u002Fproducts']?.post?.requestBody\n\n\u002F\u002F Inspect endpoint parameters\nasync () => spec.paths['\u002Fproducts']?.get?.parameters\n",[49,1129,1127],{"__ignoreMap":47},[10,1131,1132],{},"The model can now search the OpenAPI specification without receiving the complete document in its context.",[1134,1135,1136,1137,1136,1146],"figure",{},"\n  ",[1138,1139,1140,1141,1136],"video",{"autoPlay":410,"loop":410,"muted":410,"playsInline":410},"\n    ",[1142,1143],"source",{"src":1144,"type":1145},"https:\u002F\u002Fimages.soubiran.dev\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fsearching-openapi-specification-without-filling-the-context\u002Fsearch-openapi-specification.mp4","video\u002Fmp4",[1147,1148,1149],"figcaption",{},"Searching the OpenAPI specification without returning the complete document.",[10,1151,1152],{},"But why ask the LLM to write JavaScript code instead of any other language?",[10,1154,1155],{},"We ask the model to write JavaScript because it is widely used, familiar to models, and straightforward to execute in the target runtime. The TypeScript interface above is documentation for the model; it provides static types for the facade, but it is not executed.",[17,1157,1159],{"id":1158},"discovery-is-not-execution","Discovery is not execution",[10,1161,1162],{},"Knowing which endpoints to call is a good start, but not enough. Based on all the data the LLM has, it could generate the code to call the endpoint. That would close the loop. From nothing, the LLM could both learn and interact with the API.",[10,1164,1165,1166,1170,1171,1174],{},"In ",[25,1167,1169],{"href":1168},"\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters","Part 4",", we will add a separate execution capability. It will let generated code call a narrow, host-owned ",[49,1172,1173],{},"api.request()"," helper and return only the part of the response the model needs next.",[1176,1177,1178],"style",{},"html pre.shiki code .sovSZ, html code.shiki .sovSZ{--shiki-light:#22863A;--shiki-default:#22863A;--shiki-dark:#85E89D}html pre.shiki code .sxrX7, html code.shiki .sxrX7{--shiki-light:#24292E;--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sBjJW, html code.shiki .sBjJW{--shiki-light:#005CC5;--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sIIMD, html code.shiki .sIIMD{--shiki-light:#032F62;--shiki-default:#032F62;--shiki-dark:#9ECBFF}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .s8jYJ, html code.shiki .s8jYJ{--shiki-light:#D73A49;--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .snPdu, html code.shiki .snPdu{--shiki-light:#6F42C1;--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sP4rz, html code.shiki .sP4rz{--shiki-light:#E36209;--shiki-default:#E36209;--shiki-dark:#FFAB70}",{"title":47,"searchDepth":70,"depth":70,"links":1180},[1181,1182,1183,1184,1185],{"id":19,"depth":70,"text":20},{"id":301,"depth":70,"text":302},{"id":347,"depth":70,"text":348},{"id":587,"depth":70,"text":588},{"id":1158,"depth":70,"text":1159},"8c4a1e72-bf39-4d65-a08e-2c7f91b6d543","2026-07-12","Keep an OpenAPI specification server-side and search a compact typed facade without returning the complete document.","md",{"branch":1191},"part-3-search",null,{},"\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fsearching-openapi-specification-without-filling-the-context","---\ncontentId: 8c4a1e72-bf39-4d65-a08e-2c7f91b6d543\npart: 3\ntitle: Searching OpenAPI Specifications Without Filling Context\ndescription: Keep an OpenAPI specification server-side and search a compact typed facade without returning the complete document.\ngithub:\n  branch: part-3-search\ndate: 2026-07-12\nseriesSlug: building-code-mode-for-apis-with-mcp-and-isolated-workers\n---\n\nIn the previous article, we learned what Code Mode is and how useful it can be to let the model write orchestration code instead of calling tools directly.\n\nIn this third part of the series, we will explore how we can use Code Mode when the context window is limited or when we have a document—an OpenAPI specification in our case—that is larger than the context window.\n\n## The context window problem\n\nWhen developing a service or an application, we often build an API to allow other services to interact with our system. Developers traditionally learn how to use that API through documentation websites, such as the [Cloudflare API reference](https:\u002F\u002Fdevelopers.cloudflare.com\u002Fapi\u002F).\n\nTo make those websites easier to build, maintain, and keep in sync with the actual API, the industry created a specification format: [OpenAPI](https:\u002F\u002Fswagger.io\u002Fspecification\u002F).\n\n```yaml [Example]\nopenapi: 3.0.0\ninfo:\n  title: Sample API\n  version: 1.0.0\npaths:\n  \u002Fusers:\n    get:\n      summary: Get all users\n      responses:\n        '200':\n          description: A list of users\n          content:\n            application\u002Fjson:\n              schema:\n                type: array\n                items:\n                  type: object\n                  properties:\n                    id:\n                      type: string\n                    name:\n                      type: string\n```\n\nThis example shows a simple OpenAPI specification for an API that has a single endpoint `\u002Fusers` which returns a list of users. The specification describes the endpoint, the HTTP method, the expected response, and the data format.\n\nThis is powerful for programmatic use and can generate useful human-facing documentation. However, a large raw specification is difficult to navigate manually and can exceed a model's context window. In those cases, we cannot simply provide the complete document to the model and expect it to use it effectively.\n\n- [GitHub's GHES 3.21 OpenAPI specification](https:\u002F\u002Fgithub.com\u002Fgithub\u002Frest-api-description\u002Fblob\u002Fmain\u002Fdescriptions\u002Fghes-3.21\u002Fghes-3.21.json) is 11.1 MB.\n- [Cloudflare's OpenAPI specification](https:\u002F\u002Fgithub.com\u002Fcloudflare\u002Fapi-schemas\u002Fblob\u002Fmain\u002Fopenapi.json) is 22.7 MB.\n\nThese files evolve, so their exact sizes will change. The point is that real API descriptions can be far larger than the information needed for a single task.\n\nThe Cloudflare snapshot used in this series contains 23,792,523 characters. The rough shortcut of four characters per token suggests about 6 million tokens, but tokenization varies by model and content. Either way, it is much larger than many available context windows.\n\nWe cannot simply provide the entire specification to the model.\n\n## OpenAPI specifications are for people and machines\n\nOpenAPI is designed to let both people and software understand an API. A documentation generator can turn it into a website; a client generator can turn it into code. For a model, however, returning the complete specification as context is still usually the wrong interface. The model needs the relevant endpoints and schemas for the task, not every operation in the API.\n\nHowever, nothing prevents us from building a tool that can search the OpenAPI specification and return only the relevant information. Imagine, you're trying to integrate a marketplace platform and you want to know how to create a return.\n\nInstead of using `Ctrl+F` or `Cmd+F` on the OpenAPI specification, why couldn't we use this algorithm to search it?\n\n```text [Example]\nsearchTerm = \"return\"\nresults = []\n\nfor each URL path and path item in spec.paths:\n    for each HTTP method and operation in the path item:\n        if the entry is not an HTTP operation:\n            continue\n\n        searchableText = combine:\n            - the URL path\n            - the operation ID\n            - the summary\n            - the description\n            - the operation tags\n\n        if searchableText does not contain searchTerm:\n            continue\n\n        endpoint = {\n            method: the HTTP method in uppercase,\n            path: the URL path,\n            operationId: the operation ID,\n            summary: the operation summary,\n            parameters: [\n                for each parameter:\n                    keep its name, location, and required flag\n            ],\n            requestBody: keep only its content types and required flag,\n            responses: [\n                for each response:\n                    keep its status code and description\n            ]\n        }\n\n        add endpoint to results\n\nreturn results\n```\n\nThat way, we extract only the relevant information. But we can go even further.\n\nFor now, even with an algorithm like this, we still have to run the code manually and there is no way of knowing if our algorithm will handle all the cases. For example, to create a return, we could filter the results to only keep the endpoints that have a `POST` method. Maybe filtering using tags is better than trying to guess the right wording to use in the search term in summary and description. We could also filter the results to only keep the endpoints that have a `200` response code. There are so many different ways to filter the results, depending on the client, the data we need, and the task we want to perform, that writing a generic algorithm is far too complex.\n\nWe need to write a custom algorithm for each use case.\n\n## LLMs know code and algorithms\n\nOr we can delegate this task to a LLM.\n\nOne practical strength of LLMs is generating code. They can turn a task-specific request into a small search program that developers can review and execute.\n\nSo, instead of writing a generic algorithm—or thousands of them to try to cover all the cases—we could just ask the LLM to write the algorithm for us. Then, we just have to execute it. That way, the LLM gets exactly the information it needs, and we do not have to worry about the context window problem.\n\nThe first time I heard about this idea was in a Cloudflare blog post named [Code Mode](https:\u002F\u002Fblog.cloudflare.com\u002Fcode-mode\u002F) and I was \"what?\". I honestly had to read it more than twice to understand what it was about. Let me give you an example.\n\nImagine you want to create a return on a marketplace platform. Instead of giving the entire OpenAPI specification to the model, you could write the following method:\n\n```js [Example]\nasync () => {\n  const results = []\n\n  for (const [path, methods] of Object.entries(spec.paths)) {\n    const operation = methods.post\n\n    if (operation?.tags?.some(tag => tag.toLowerCase() === 'returns')) {\n      results.push({\n        method: 'POST',\n        path,\n        summary: operation.summary,\n        requestBody: operation.requestBody\n      })\n    }\n  }\n\n  return results\n}\n```\n\nWith the code above, we can quickly search the OpenAPI specification and return only the relevant information.\n\nBut who wants to write this code? Nobody.\n\nFortunately, LLMs can generate this code for us. Give them access to the OpenAPI specification and a couple of examples, and LLMs can search the entire specification to find only what is relevant.\n\n## Tool, description and language\n\nIn our MCP, the search tool would look like this:\n\n```typescript [search.ts]\nserver.registerTool(\n  'search',\n  {\n    title: 'Search OpenAPI Specification',\n    description: '...',\n    inputSchema: z.object({\n      code: z\n        .string()\n        .max(MAX_CODE_LENGTH)\n        .describe('An async arrow function that searches the OpenAPI spec')\n    }),\n  },\n  async ({ code }) => {\n    try {\n      const result = await evaluateSearchCode(code)\n      return { content: [{ type: 'text', text: formatSearchResult(result) }] }\n    }\n    catch (error) {\n      return {\n        content: [{ type: 'text', text: `Search failed: ${errorMessage(error)}` }],\n        isError: true\n      }\n    }\n  }\n)\n```\n\nFrom a high-level perspective, there is nothing more than what we have already seen in the previous article. The details are in the description and the evaluation function.\n\nThe description starts like any other tool description: what is the tool about, and what can the model do with it?\n\n```text [Example]\nSearch the MarketHub OpenAPI specification with JavaScript.\n\nThe specification stays inside the server. Your code must be an async arrow function and should return only the small result needed for the next decision. All local $refs are resolved before the code runs.\n```\n\nThen, things start to get interesting.\n\nWe can provide TypeScript interfaces to give the model a typed facade against which to write code. This compact contract improves the chance that the model writes a working program on its first attempt.\n\n```typescript [Example]\ninterface OperationInfo {\n  operationId?: string\n  summary?: string\n  description?: string\n  tags?: string[]\n  parameters?: Array\u003C{\n    name?: string\n    in?: string\n    required?: boolean\n    description?: string\n    schema?: unknown\n  }>\n  requestBody?: unknown\n  responses?: Record\u003Cstring, unknown>\n}\n\ndeclare const spec: {\n  paths: Record\u003Cstring, {\n    get?: OperationInfo\n    post?: OperationInfo\n    put?: OperationInfo\n    patch?: OperationInfo\n    delete?: OperationInfo\n  }>\n}\n```\n\nThe full OpenAPI specification stays on the server. The generated program can inspect it through this facade, while the model receives only the compact interface and the final search result.\n\n::callout{icon=\"i-ph-info-duotone\" color=\"info\"}\nThe OpenAPI specification is simplified in the MCP to make it more AI-friendly.\n::\n\nAnd finally, here are a couple of examples to show the model how to use the tool and what is expected as a result.\n\n```text [Example]\n\u002F\u002F Inspect one operation's request body\nasync () => spec.paths['\u002Fproducts']?.post?.requestBody\n\n\u002F\u002F Inspect endpoint parameters\nasync () => spec.paths['\u002Fproducts']?.get?.parameters\n```\n\nThe model can now search the OpenAPI specification without receiving the complete document in its context.\n\n\u003Cfigure>\n  \u003Cvideo autoplay loop muted playsinline>\n    \u003Csource src=\"https:\u002F\u002Fimages.soubiran.dev\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fsearching-openapi-specification-without-filling-the-context\u002Fsearch-openapi-specification.mp4\" type=\"video\u002Fmp4\">\n  \u003C\u002Fvideo>\n  \u003Cfigcaption>Searching the OpenAPI specification without returning the complete document.\u003C\u002Ffigcaption>\n\u003C\u002Ffigure>\n\nBut why ask the LLM to write JavaScript code instead of any other language?\n\nWe ask the model to write JavaScript because it is widely used, familiar to models, and straightforward to execute in the target runtime. The TypeScript interface above is documentation for the model; it provides static types for the facade, but it is not executed.\n\n## Discovery is not execution\n\nKnowing which endpoints to call is a good start, but not enough. Based on all the data the LLM has, it could generate the code to call the endpoint. That would close the loop. From nothing, the LLM could both learn and interact with the API.\n\nIn [Part 4](\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters), we will add a separate execution capability. It will let generated code call a narrow, host-owned `api.request()` helper and return only the part of the response the model needs next.\n",{"title":5,"description":1188},"building-code-mode-for-apis-with-mcp-and-isolated-workers",{"loc":1194},"series\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fsearching-openapi-specification-without-filling-the-context","d1k0jqrEB49LBXl2wOZ8oS1Um_fPntepPIEA4gAjiMo",{"overview":1202,"chapters":1365},{"id":1203,"title":1204,"body":1205,"contentId":1347,"date":1187,"description":1348,"extension":1189,"github":1349,"meetTheInstructor":1350,"meta":1351,"navigation":410,"part":1192,"path":1352,"rawbody":1353,"robots":1192,"schemaOrg":1192,"seo":1354,"seriesSlug":1197,"sitemap":1355,"stem":1356,"subtitle":1357,"topics":1358,"__hash__":1364},"series\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers.md","Building Code Mode for APIs with MCP and Isolated Workers",{"type":7,"value":1206,"toc":1344},[1207,1210,1218,1225,1237,1253,1256,1259,1262,1318,1326,1334,1338],[10,1208,1209],{},"Hello and welcome! 👋",[10,1211,1212,1213,1217],{},"This series is a practical follow-up to ",[25,1214,1216],{"href":1215},"\u002Fposts\u002Fcode-mode-two-tools-and-an-mcp-can-save-your-llm-context","Code Mode, Two Tools, and an MCP Can Save Your LLM Context",". That article introduced the idea: instead of making a model orchestrate every dependent tool call, let it write the orchestration as code and return only the result needed for its next decision.",[10,1219,1220,1221,1224],{},"Here, we will build that idea step by step. We will start with a small local file transformation, move to an OpenAPI-described API, and then replace the trusted local evaluator based on the ",[49,1222,1223],{},"Function"," constructor with an isolated runtime. The final result will be a locally runnable MCP server that can search an API specification and execute a narrow request against the API.",[10,1226,1227,1228,1232,1233,31],{},"MCP fundamentals are outside the scope of this series. If you need an introduction to the protocol or to the basic relationship between an AI agent and an MCP server, begin with ",[25,1229,1231],{"href":1230},"\u002Fseries\u002Fai-agents-and-mcp-server-teaming-up-for-the-agentic-web","AI Agents and MCP Server: Teaming Up for the Agentic Web",", especially ",[25,1234,1236],{"href":1235},"\u002Fseries\u002Fai-agents-and-mcp-server-teaming-up-for-the-agentic-web\u002Fmcp-to-provide-additional-capabilities-to-the-ai-agent","its MCP server article",[10,1238,1239,1240,1244,1245,1248,1249,1252],{},"Throughout the series, the ",[1241,1242,1243],"strong",{},"model"," generates tool calls or code, the ",[1241,1246,1247],{},"MCP client"," (or agent) runs the model loop, and the ",[1241,1250,1251],{},"MCP server"," provides the capabilities. Keeping these roles separate is important: the host, not generated code, defines which capabilities are available.",[10,1254,1255],{},"The central idea is simple: with direct MCP tools, the model must call one tool, receive the complete intermediate result, and then use that result to decide how to call the next tool. With Code Mode, the model writes the orchestration as code, the code accesses the capabilities it needs inside the execution environment, and the model receives only the desired final result to continue.",[10,1257,1258],{},"Code Mode is not automatically the right choice. Direct MCP tools remain simpler for small, obvious actions. The extra runtime is worthwhile when a task contains dependent calls, requires local data processing, or needs to navigate a large and evolving API surface, like an OpenAPI specification that can be larger than the model's context window.",[10,1260,1261],{},"Throughout this journey, we will:",[1263,1264,1265,1275,1290,1299,1312],"ol",{},[274,1266,1267,1270,1271,1274],{},[1241,1268,1269],{},"Beyond One Tool Call at a Time: Introducing Code Mode",": Build two direct ",[49,1272,1273],{},"Drive"," tools over a Markdown fixture and observe how the complete file content travels through the model's context before the next tool call.",[274,1276,1277,1280,1281,1283,1284,1286,1287,1289],{},[1241,1278,1279],{},"Let the Model Orchestrate Tools with a Local Code Runtime",": Replace the two direct tools with one generic ",[49,1282,49],{}," tool, expose a typed ",[49,1285,1273],{}," facade, and introduce the executor interface that later parts will replace. The local evaluator based on the ",[49,1288,1223],{}," constructor is intentionally a trusted development shortcut, not a production sandbox.",[274,1291,1292,1294,1295,1298],{},[1241,1293,5],{},": Keep the OpenAPI document inside the server, resolve its local ",[49,1296,1297],{},"$ref"," values, and let generated code search a compact type facade instead of returning the complete specification to the model.",[274,1300,1301,1304,1305,1308,1309,1311],{},[1241,1302,1303],{},"Calling APIs with Code Mode and Returning Only What Matters",": Add a separate ",[49,1306,1307],{},"execute"," tool with a host-owned ",[49,1310,1173],{}," helper. We will validate request options, call the local MarketHub fixture, and return a narrow projection rather than the complete API response.",[274,1313,1314,1317],{},[1241,1315,1316],{},"Replacing the Evaluator with Isolated Cloudflare Workers",": Swap only the executor boundary for fresh Dynamic Workers. Search will run without outbound access, execute will use an allowlisted gateway, and credentials will remain outside generated code. We will also cover result bounds, resource limits, and host deadlines.",[10,1319,1320,1321,1325],{},"The companion repository, ",[1322,1323],"git-hub-link",{"repo":1324},"barbapapazes\u002Fcode-mode",", is an executable textbook for the series. Each article has a complete checkpoint branch, a small evaluation, and a focused diff from the previous step. I recommend that you check out a branch and inspect the implementation for a better understanding of the concepts, as the articles will not cover every detail.",[1115,1327,1328],{"color":73,"icon":1117},[10,1329,1330,1331,1333],{},"This series assumes familiarity with TypeScript, JavaScript promises, HTTP APIs, and basic MCP concepts. The local checkpoints contain no credentials. Parts 2 through 4 use a trusted local evaluator based on the ",[49,1332,1223],{}," constructor for development, while Part 5 provides a Cloudflare deployment scaffold and structural security evaluation.",[17,1335,1337],{"id":1336},"chapters","Chapters",[1339,1340],"series-chapters-list",{"className":1341},[1342,1343],"mx-auto","max-w-5xl",{"title":47,"searchDepth":70,"depth":70,"links":1345},[1346],{"id":1336,"depth":70,"text":1337},"8f6d8d8d-9cc8-4ed3-9f2d-4e3d0b7a4d91","Build an MCP server for an OpenAPI-described API, then replace a trusted local evaluator with isolated Cloudflare Dynamic Workers.",{"name":365,"repository":1324},"I created this series to turn the Code Mode idea into a practical implementation. We will start with two ordinary MCP tools, move the orchestration into generated code, and finish by replacing a trusted local evaluator based on the Function constructor with isolated Cloudflare Dynamic Workers.",{},"\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers","---\ncontentId: 8f6d8d8d-9cc8-4ed3-9f2d-4e3d0b7a4d91\ntitle: Building Code Mode for APIs with MCP and Isolated Workers\nsubtitle: Build a context-efficient MCP server for OpenAPI-described APIs\ndescription: Build an MCP server for an OpenAPI-described API, then replace a trusted local evaluator with isolated Cloudflare Dynamic Workers.\ndate: 2026-07-12\ntopics:\n  - ai\n  - ai-agents\n  - mcp\n  - code-mode\n  - openapi\n  - cloudflare\n  - typescript\ngithub:\n  name: Code Mode\n  repository: barbapapazes\u002Fcode-mode\nmeetTheInstructor: I created this series to turn the Code Mode idea into a practical implementation. We will start with two ordinary MCP tools, move the orchestration into generated code, and finish by replacing a trusted local evaluator based on the Function constructor with isolated Cloudflare Dynamic Workers.\nseriesSlug: building-code-mode-for-apis-with-mcp-and-isolated-workers\n---\n\nHello and welcome! 👋\n\nThis series is a practical follow-up to [Code Mode, Two Tools, and an MCP Can Save Your LLM Context](\u002Fposts\u002Fcode-mode-two-tools-and-an-mcp-can-save-your-llm-context). That article introduced the idea: instead of making a model orchestrate every dependent tool call, let it write the orchestration as code and return only the result needed for its next decision.\n\nHere, we will build that idea step by step. We will start with a small local file transformation, move to an OpenAPI-described API, and then replace the trusted local evaluator based on the `Function` constructor with an isolated runtime. The final result will be a locally runnable MCP server that can search an API specification and execute a narrow request against the API.\n\nMCP fundamentals are outside the scope of this series. If you need an introduction to the protocol or to the basic relationship between an AI agent and an MCP server, begin with [AI Agents and MCP Server: Teaming Up for the Agentic Web](\u002Fseries\u002Fai-agents-and-mcp-server-teaming-up-for-the-agentic-web), especially [its MCP server article](\u002Fseries\u002Fai-agents-and-mcp-server-teaming-up-for-the-agentic-web\u002Fmcp-to-provide-additional-capabilities-to-the-ai-agent).\n\nThroughout the series, the **model** generates tool calls or code, the **MCP client** (or agent) runs the model loop, and the **MCP server** provides the capabilities. Keeping these roles separate is important: the host, not generated code, defines which capabilities are available.\n\nThe central idea is simple: with direct MCP tools, the model must call one tool, receive the complete intermediate result, and then use that result to decide how to call the next tool. With Code Mode, the model writes the orchestration as code, the code accesses the capabilities it needs inside the execution environment, and the model receives only the desired final result to continue.\n\nCode Mode is not automatically the right choice. Direct MCP tools remain simpler for small, obvious actions. The extra runtime is worthwhile when a task contains dependent calls, requires local data processing, or needs to navigate a large and evolving API surface, like an OpenAPI specification that can be larger than the model's context window.\n\nThroughout this journey, we will:\n\n1. **Beyond One Tool Call at a Time: Introducing Code Mode**: Build two direct `Drive` tools over a Markdown fixture and observe how the complete file content travels through the model's context before the next tool call.\n2. **Let the Model Orchestrate Tools with a Local Code Runtime**: Replace the two direct tools with one generic `code` tool, expose a typed `Drive` facade, and introduce the executor interface that later parts will replace. The local evaluator based on the `Function` constructor is intentionally a trusted development shortcut, not a production sandbox.\n3. **Searching OpenAPI Specifications Without Filling Context**: Keep the OpenAPI document inside the server, resolve its local `$ref` values, and let generated code search a compact type facade instead of returning the complete specification to the model.\n4. **Calling APIs with Code Mode and Returning Only What Matters**: Add a separate `execute` tool with a host-owned `api.request()` helper. We will validate request options, call the local MarketHub fixture, and return a narrow projection rather than the complete API response.\n5. **Replacing the Evaluator with Isolated Cloudflare Workers**: Swap only the executor boundary for fresh Dynamic Workers. Search will run without outbound access, execute will use an allowlisted gateway, and credentials will remain outside generated code. We will also cover result bounds, resource limits, and host deadlines.\n\nThe companion repository, \u003CGitHubLink repo=\"barbapapazes\u002Fcode-mode\" \u002F>, is an executable textbook for the series. Each article has a complete checkpoint branch, a small evaluation, and a focused diff from the previous step. I recommend that you check out a branch and inspect the implementation for a better understanding of the concepts, as the articles will not cover every detail.\n\n::callout{icon=\"i-ph-info-duotone\" color=\"info\"}\nThis series assumes familiarity with TypeScript, JavaScript promises, HTTP APIs, and basic MCP concepts. The local checkpoints contain no credentials. Parts 2 through 4 use a trusted local evaluator based on the `Function` constructor for development, while Part 5 provides a Cloudflare deployment scaffold and structural security evaluation.\n::\n\n## Chapters\n\n::series-chapters-list\n---\nclass: mx-auto max-w-5xl\n---\n::\n",{"title":1204,"description":1348},{"loc":1352},"series\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers","Build a context-efficient MCP server for OpenAPI-described APIs",[1359,1360,1361,1362,59,1363,597],"ai","ai-agents","mcp","code-mode","cloudflare","WgDRYOu5CDIYY78O1GSEOv6BKbIsrTVwVf8cTOkdsOA",[1366,1372,1378,1380,1385],{"contentId":1367,"title":1269,"description":1368,"path":1369,"part":55,"github":1370,"topics":1192},"6f0c6f18-8d31-4b4d-aea6-9b2df779a0d1","See why dependent direct MCP tool calls make intermediate content part of model context, and how Code Mode moves orchestration into generated code.","\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fbeyond-one-tool-call-at-a-time-introducing-code-mode",{"branch":1371},"part-1-direct-tools",{"contentId":1373,"title":1279,"description":1374,"path":1375,"part":70,"github":1376,"topics":1192},"2a9e7d4c-1f6b-4c83-9d52-7e0a6b3f4189","Build a minimal trusted local Code Mode runtime with a typed Drive facade and an executor seam ready for isolation.","\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Flet-the-model-orchestrate-tools-with-a-local-code-runtime",{"branch":1377},"part-2-generic-code-mode",{"contentId":1186,"title":5,"description":1188,"path":1194,"part":79,"github":1379,"topics":1192},{"branch":1191},{"contentId":1381,"title":1303,"description":1382,"path":1168,"part":91,"github":1383,"topics":1192},"1d7b5e93-6a24-4f80-bc19-3e8d0a572f16","Use a host-owned API request helper to validate and execute a narrow API call, then return only the useful projection.",{"branch":1384},"part-4-local-execute",{"contentId":1386,"title":1316,"description":1387,"path":1388,"part":102,"github":1389,"topics":1192},"5e3a9c71-2b48-4d06-8f95-c7a1e0b6342d","Replace a trusted local Function evaluator with isolated Cloudflare Dynamic Workers, controlled outbound access, and bounded execution results.","\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Freplacing-local-eval-with-isolated-cloudflare-workers",{"branch":1390},"part-5-dynamic-workers",1795016691500]