[{"data":1,"prerenderedAt":1859},["ShallowReactive",2],{"series-\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters":3,"series-context-\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers":1664},{"id":4,"title":5,"body":6,"contentId":1649,"date":1650,"description":1651,"extension":1652,"github":1653,"meetTheInstructor":1655,"meta":1656,"navigation":768,"part":186,"path":1657,"rawbody":1658,"robots":1655,"schemaOrg":1655,"seo":1659,"seriesSlug":1660,"sitemap":1661,"stem":1662,"subtitle":1655,"topics":1655,"__hash__":1663},"series\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters.md","Calling APIs with Code Mode and Returning Only What Matters",{"type":7,"value":8,"toc":1642},"minimark",[9,13,16,21,24,155,268,271,274,278,281,284,597,600,603,621,624,633,636,959,970,973,1111,1128,1132,1135,1138,1141,1440,1443,1447,1450,1453,1509,1512,1515,1525,1528,1531,1534,1618,1621,1625,1628,1631,1638],[10,11,12],"p",{},"We have seen how to let the model write JavaScript code to search an OpenAPI specification that is larger than the context window. The specification can grow over time, although the runtime still has practical limits on execution time, memory, and returned data.",[10,14,15],{},"Now, we'll see how to let the model write JavaScript to interact with our API, based on the knowledge it has gathered from the OpenAPI specification.",[17,18,20],"h2",{"id":19},"our-mcp-needs-a-second-tool","Our MCP needs a second tool",[10,22,23],{},"Our goal was to create a system that makes interactions between the LLM and our API easier. For now, our LLM can retrieve and understand the API surface:",[25,26,32],"pre",{"className":27,"code":28,"filename":29,"language":30,"meta":31,"style":31},"language-json shiki shiki-themes github-light github-light github-dark","{\n  \"code\": \"async () => {\\n  const results = [];\\n  for (const [path, methods] of Object.entries(spec.paths)) {\\n    for (const [method, operation] of Object.entries(methods)) {\\n      if (operation?.tags?.some(tag => tag.toLowerCase() === 'returns')) {\\n        results.push({\\n          method: method.toUpperCase(),\\n          path,\\n          operationId: operation.operationId,\\n          summary: operation.summary,\\n          description: operation.description,\\n          parameters: operation.parameters,\\n          requestBody: operation.requestBody,\\n        });\\n      }\\n    }\\n  }\\n  return results;\\n}\"\n}\n","LLM Tool Call","json","",[33,34,35,44,149],"code",{"__ignoreMap":31},[36,37,40],"span",{"class":38,"line":39},"line",1,[36,41,43],{"class":42},"sxrX7","{\n",[36,45,47,51,54,58,61,64,66,69,71,74,76,79,81,84,86,89,91,94,96,99,101,104,106,109,111,114,116,119,121,124,126,129,131,134,136,139,141,144,146],{"class":38,"line":46},2,[36,48,50],{"class":49},"sBjJW","  \"code\"",[36,52,53],{"class":42},": ",[36,55,57],{"class":56},"sIIMD","\"async () => {",[36,59,60],{"class":49},"\\n",[36,62,63],{"class":56},"  const results = [];",[36,65,60],{"class":49},[36,67,68],{"class":56},"  for (const [path, methods] of Object.entries(spec.paths)) {",[36,70,60],{"class":49},[36,72,73],{"class":56},"    for (const [method, operation] of Object.entries(methods)) {",[36,75,60],{"class":49},[36,77,78],{"class":56},"      if (operation?.tags?.some(tag => tag.toLowerCase() === 'returns')) {",[36,80,60],{"class":49},[36,82,83],{"class":56},"        results.push({",[36,85,60],{"class":49},[36,87,88],{"class":56},"          method: method.toUpperCase(),",[36,90,60],{"class":49},[36,92,93],{"class":56},"          path,",[36,95,60],{"class":49},[36,97,98],{"class":56},"          operationId: operation.operationId,",[36,100,60],{"class":49},[36,102,103],{"class":56},"          summary: operation.summary,",[36,105,60],{"class":49},[36,107,108],{"class":56},"          description: operation.description,",[36,110,60],{"class":49},[36,112,113],{"class":56},"          parameters: operation.parameters,",[36,115,60],{"class":49},[36,117,118],{"class":56},"          requestBody: operation.requestBody,",[36,120,60],{"class":49},[36,122,123],{"class":56},"        });",[36,125,60],{"class":49},[36,127,128],{"class":56},"      }",[36,130,60],{"class":49},[36,132,133],{"class":56},"    }",[36,135,60],{"class":49},[36,137,138],{"class":56},"  }",[36,140,60],{"class":49},[36,142,143],{"class":56},"  return results;",[36,145,60],{"class":49},[36,147,148],{"class":56},"}\"\n",[36,150,152],{"class":38,"line":151},3,[36,153,154],{"class":42},"}\n",[25,156,159],{"className":27,"code":157,"filename":158,"language":30,"meta":31,"style":31},"[\n  {\n    \"method\": \"GET\",\n    \"path\": \"\u002Freturns\",\n    \"operationId\": \"listReturns\",\n    \"summary\": \"List return requests\",\n    \"description\": \"List return requests, optionally narrowed to an order, order item, seller, or return status.\",\n    \"parameters\": [],\n    \"requestBody\": null\n  }\n]\n","LLM Tool Output",[33,160,161,166,171,184,197,210,223,236,245,256,262],{"__ignoreMap":31},[36,162,163],{"class":38,"line":39},[36,164,165],{"class":42},"[\n",[36,167,168],{"class":38,"line":46},[36,169,170],{"class":42},"  {\n",[36,172,173,176,178,181],{"class":38,"line":151},[36,174,175],{"class":49},"    \"method\"",[36,177,53],{"class":42},[36,179,180],{"class":56},"\"GET\"",[36,182,183],{"class":42},",\n",[36,185,187,190,192,195],{"class":38,"line":186},4,[36,188,189],{"class":49},"    \"path\"",[36,191,53],{"class":42},[36,193,194],{"class":56},"\"\u002Freturns\"",[36,196,183],{"class":42},[36,198,200,203,205,208],{"class":38,"line":199},5,[36,201,202],{"class":49},"    \"operationId\"",[36,204,53],{"class":42},[36,206,207],{"class":56},"\"listReturns\"",[36,209,183],{"class":42},[36,211,213,216,218,221],{"class":38,"line":212},6,[36,214,215],{"class":49},"    \"summary\"",[36,217,53],{"class":42},[36,219,220],{"class":56},"\"List return requests\"",[36,222,183],{"class":42},[36,224,226,229,231,234],{"class":38,"line":225},7,[36,227,228],{"class":49},"    \"description\"",[36,230,53],{"class":42},[36,232,233],{"class":56},"\"List return requests, optionally narrowed to an order, order item, seller, or return status.\"",[36,235,183],{"class":42},[36,237,239,242],{"class":38,"line":238},8,[36,240,241],{"class":49},"    \"parameters\"",[36,243,244],{"class":42},": [],\n",[36,246,248,251,253],{"class":38,"line":247},9,[36,249,250],{"class":49},"    \"requestBody\"",[36,252,53],{"class":42},[36,254,255],{"class":49},"null\n",[36,257,259],{"class":38,"line":258},10,[36,260,261],{"class":42},"  }\n",[36,263,265],{"class":38,"line":264},11,[36,266,267],{"class":42},"]\n",[10,269,270],{},"However, it cannot interact with it.",[10,272,273],{},"To do so, we need to provide it with a second tool: the executor.",[17,275,277],{"id":276},"the-executor-tool","The executor tool",[10,279,280],{},"The executor tool completes the duo of the search tool. Under the hood, it is a wrapper around a pre-configured API client, a fetch function in our case, that will allow the model to call the API using the information it has gathered from the OpenAPI specification.",[10,282,283],{},"At a high level, it is very similar to the search tool, with the same idea of providing the model with a pre-configured playground to write code against a predefined typed API. The model is responsible for orchestrating one or multiple requests, depending on the complexity of the task, and returning only what matters.",[25,285,290],{"className":286,"code":287,"filename":288,"language":289,"meta":31,"style":31},"language-typescript shiki shiki-themes github-light github-light github-dark","export function registerExecuteTool(server: McpServer): void {\n  server.registerTool(\n    'execute',\n    {\n      title: 'MarketHub API Code Executor',\n      description: '...',\n      inputSchema: z.object({\n        code: z\n          .string()\n          .max(MAX_CODE_LENGTH)\n          .describe('An async arrow function that executes a MarketHub API request')\n      }),\n    },\n    async ({ code }) => {\n      try {\n        const result = await evaluateExecuteCode(code)\n        return { content: [{ type: 'text', text: formatExecuteResult(result) }] }\n      }\n      catch (error) {\n        return {\n          content: [{ type: 'text', text: `Execute failed: ${errorMessage(error)}` }],\n          isError: true\n        }\n      }\n    }\n  )\n}\n","executor.ts","typescript",[33,291,292,329,340,347,352,362,372,383,388,399,414,428,434,440,459,467,488,509,515,524,531,560,569,575,580,586,592],{"__ignoreMap":31},[36,293,294,298,301,305,308,312,315,318,321,323,326],{"class":38,"line":39},[36,295,297],{"class":296},"s8jYJ","export",[36,299,300],{"class":296}," function",[36,302,304],{"class":303},"snPdu"," registerExecuteTool",[36,306,307],{"class":42},"(",[36,309,311],{"class":310},"sP4rz","server",[36,313,314],{"class":296},":",[36,316,317],{"class":303}," McpServer",[36,319,320],{"class":42},")",[36,322,314],{"class":296},[36,324,325],{"class":49}," void",[36,327,328],{"class":42}," {\n",[36,330,331,334,337],{"class":38,"line":46},[36,332,333],{"class":42},"  server.",[36,335,336],{"class":303},"registerTool",[36,338,339],{"class":42},"(\n",[36,341,342,345],{"class":38,"line":151},[36,343,344],{"class":56},"    'execute'",[36,346,183],{"class":42},[36,348,349],{"class":38,"line":186},[36,350,351],{"class":42},"    {\n",[36,353,354,357,360],{"class":38,"line":199},[36,355,356],{"class":42},"      title: ",[36,358,359],{"class":56},"'MarketHub API Code Executor'",[36,361,183],{"class":42},[36,363,364,367,370],{"class":38,"line":212},[36,365,366],{"class":42},"      description: ",[36,368,369],{"class":56},"'...'",[36,371,183],{"class":42},[36,373,374,377,380],{"class":38,"line":225},[36,375,376],{"class":42},"      inputSchema: z.",[36,378,379],{"class":303},"object",[36,381,382],{"class":42},"({\n",[36,384,385],{"class":38,"line":238},[36,386,387],{"class":42},"        code: z\n",[36,389,390,393,396],{"class":38,"line":247},[36,391,392],{"class":42},"          .",[36,394,395],{"class":303},"string",[36,397,398],{"class":42},"()\n",[36,400,401,403,406,408,411],{"class":38,"line":258},[36,402,392],{"class":42},[36,404,405],{"class":303},"max",[36,407,307],{"class":42},[36,409,410],{"class":49},"MAX_CODE_LENGTH",[36,412,413],{"class":42},")\n",[36,415,416,418,421,423,426],{"class":38,"line":264},[36,417,392],{"class":42},[36,419,420],{"class":303},"describe",[36,422,307],{"class":42},[36,424,425],{"class":56},"'An async arrow function that executes a MarketHub API request'",[36,427,413],{"class":42},[36,429,431],{"class":38,"line":430},12,[36,432,433],{"class":42},"      }),\n",[36,435,437],{"class":38,"line":436},13,[36,438,439],{"class":42},"    },\n",[36,441,443,446,449,451,454,457],{"class":38,"line":442},14,[36,444,445],{"class":296},"    async",[36,447,448],{"class":42}," ({ ",[36,450,33],{"class":310},[36,452,453],{"class":42}," }) ",[36,455,456],{"class":296},"=>",[36,458,328],{"class":42},[36,460,462,465],{"class":38,"line":461},15,[36,463,464],{"class":296},"      try",[36,466,328],{"class":42},[36,468,470,473,476,479,482,485],{"class":38,"line":469},16,[36,471,472],{"class":296},"        const",[36,474,475],{"class":49}," result",[36,477,478],{"class":296}," =",[36,480,481],{"class":296}," await",[36,483,484],{"class":303}," evaluateExecuteCode",[36,486,487],{"class":42},"(code)\n",[36,489,491,494,497,500,503,506],{"class":38,"line":490},17,[36,492,493],{"class":296},"        return",[36,495,496],{"class":42}," { content: [{ type: ",[36,498,499],{"class":56},"'text'",[36,501,502],{"class":42},", text: ",[36,504,505],{"class":303},"formatExecuteResult",[36,507,508],{"class":42},"(result) }] }\n",[36,510,512],{"class":38,"line":511},18,[36,513,514],{"class":42},"      }\n",[36,516,518,521],{"class":38,"line":517},19,[36,519,520],{"class":296},"      catch",[36,522,523],{"class":42}," (error) {\n",[36,525,527,529],{"class":38,"line":526},20,[36,528,493],{"class":296},[36,530,328],{"class":42},[36,532,534,537,539,541,544,547,549,552,554,557],{"class":38,"line":533},21,[36,535,536],{"class":42},"          content: [{ type: ",[36,538,499],{"class":56},[36,540,502],{"class":42},[36,542,543],{"class":56},"`Execute failed: ${",[36,545,546],{"class":303},"errorMessage",[36,548,307],{"class":56},[36,550,551],{"class":42},"error",[36,553,320],{"class":56},[36,555,556],{"class":56},"}`",[36,558,559],{"class":42}," }],\n",[36,561,563,566],{"class":38,"line":562},22,[36,564,565],{"class":42},"          isError: ",[36,567,568],{"class":49},"true\n",[36,570,572],{"class":38,"line":571},23,[36,573,574],{"class":42},"        }\n",[36,576,578],{"class":38,"line":577},24,[36,579,514],{"class":42},[36,581,583],{"class":38,"line":582},25,[36,584,585],{"class":42},"    }\n",[36,587,589],{"class":38,"line":588},26,[36,590,591],{"class":42},"  )\n",[36,593,595],{"class":38,"line":594},27,[36,596,154],{"class":42},[10,598,599],{},"As you can see, the similarity with the search tool is obvious. We take a JavaScript arrow function as input, evaluate it, and return the result.",[10,601,602],{},"Two important differences to note:",[604,605,606,610],"ol",{},[607,608,609],"li",{},"The description is shaped to make the model understand that it can write code against the API, and that it should return only what matters.",[607,611,612,613,616,617,620],{},"We use ",[33,614,615],{},"evaluateExecuteCode"," instead of ",[33,618,619],{},"evaluateSearchCode",". At their core, both evaluate code, but the data provided in the context is different.",[10,622,623],{},"The description starts by explaining succinctly what the tool does.",[25,625,631],{"className":626,"code":628,"filename":629,"language":630,"meta":31},[627],"language-text","Execute JavaScript code against the local MarketHub API.\n\nFirst use the 'search' tool to find the right endpoint, method, parameters, and request body, then write code using api.request().\n","Example","text",[33,632,628],{"__ignoreMap":31},[10,634,635],{},"Then, the description provides a TypeScript interface to give the model complete knowledge of how to write code.",[25,637,639],{"className":286,"code":638,"filename":629,"language":289,"meta":31,"style":31},"interface ApiRequestOptions {\n  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'\n  path: string\n  query?: Record\u003Cstring, string | number | boolean | undefined>\n  body?: unknown\n  contentType?: string\n  rawBody?: boolean\n}\n\ninterface ApiResponse\u003CT = unknown> {\n  success: boolean\n  status: number\n  result: T\n  errors: Array\u003C{ code: string | number, message: string }>\n  messages: Array\u003C{ code: string | number, message: string }>\n}\n\ndeclare const api: {\n  request: \u003CT = unknown>(options: ApiRequestOptions) => Promise\u003CApiResponse\u003CT>>\n}\n",[33,640,641,651,682,692,731,741,750,760,764,770,790,799,809,819,855,886,890,894,909,955],{"__ignoreMap":31},[36,642,643,646,649],{"class":38,"line":39},[36,644,645],{"class":296},"interface",[36,647,648],{"class":303}," ApiRequestOptions",[36,650,328],{"class":42},[36,652,653,656,658,661,664,667,669,672,674,677,679],{"class":38,"line":46},[36,654,655],{"class":310},"  method",[36,657,314],{"class":296},[36,659,660],{"class":56}," 'GET'",[36,662,663],{"class":296}," |",[36,665,666],{"class":56}," 'POST'",[36,668,663],{"class":296},[36,670,671],{"class":56}," 'PUT'",[36,673,663],{"class":296},[36,675,676],{"class":56}," 'PATCH'",[36,678,663],{"class":296},[36,680,681],{"class":56}," 'DELETE'\n",[36,683,684,687,689],{"class":38,"line":151},[36,685,686],{"class":310},"  path",[36,688,314],{"class":296},[36,690,691],{"class":49}," string\n",[36,693,694,697,700,703,706,708,711,713,715,718,720,723,725,728],{"class":38,"line":186},[36,695,696],{"class":310},"  query",[36,698,699],{"class":296},"?:",[36,701,702],{"class":303}," Record",[36,704,705],{"class":42},"\u003C",[36,707,395],{"class":49},[36,709,710],{"class":42},", ",[36,712,395],{"class":49},[36,714,663],{"class":296},[36,716,717],{"class":49}," number",[36,719,663],{"class":296},[36,721,722],{"class":49}," boolean",[36,724,663],{"class":296},[36,726,727],{"class":49}," undefined",[36,729,730],{"class":42},">\n",[36,732,733,736,738],{"class":38,"line":199},[36,734,735],{"class":310},"  body",[36,737,699],{"class":296},[36,739,740],{"class":49}," unknown\n",[36,742,743,746,748],{"class":38,"line":212},[36,744,745],{"class":310},"  contentType",[36,747,699],{"class":296},[36,749,691],{"class":49},[36,751,752,755,757],{"class":38,"line":225},[36,753,754],{"class":310},"  rawBody",[36,756,699],{"class":296},[36,758,759],{"class":49}," boolean\n",[36,761,762],{"class":38,"line":238},[36,763,154],{"class":42},[36,765,766],{"class":38,"line":247},[36,767,769],{"emptyLinePlaceholder":768},true,"\n",[36,771,772,774,777,779,782,784,787],{"class":38,"line":258},[36,773,645],{"class":296},[36,775,776],{"class":303}," ApiResponse",[36,778,705],{"class":42},[36,780,781],{"class":303},"T",[36,783,478],{"class":296},[36,785,786],{"class":49}," unknown",[36,788,789],{"class":42},"> {\n",[36,791,792,795,797],{"class":38,"line":264},[36,793,794],{"class":310},"  success",[36,796,314],{"class":296},[36,798,759],{"class":49},[36,800,801,804,806],{"class":38,"line":430},[36,802,803],{"class":310},"  status",[36,805,314],{"class":296},[36,807,808],{"class":49}," number\n",[36,810,811,814,816],{"class":38,"line":436},[36,812,813],{"class":310},"  result",[36,815,314],{"class":296},[36,817,818],{"class":303}," T\n",[36,820,821,824,826,829,832,834,836,839,841,843,845,848,850,852],{"class":38,"line":442},[36,822,823],{"class":310},"  errors",[36,825,314],{"class":296},[36,827,828],{"class":303}," Array",[36,830,831],{"class":42},"\u003C{ ",[36,833,33],{"class":310},[36,835,314],{"class":296},[36,837,838],{"class":49}," string",[36,840,663],{"class":296},[36,842,717],{"class":49},[36,844,710],{"class":42},[36,846,847],{"class":310},"message",[36,849,314],{"class":296},[36,851,838],{"class":49},[36,853,854],{"class":42}," }>\n",[36,856,857,860,862,864,866,868,870,872,874,876,878,880,882,884],{"class":38,"line":461},[36,858,859],{"class":310},"  messages",[36,861,314],{"class":296},[36,863,828],{"class":303},[36,865,831],{"class":42},[36,867,33],{"class":310},[36,869,314],{"class":296},[36,871,838],{"class":49},[36,873,663],{"class":296},[36,875,717],{"class":49},[36,877,710],{"class":42},[36,879,847],{"class":310},[36,881,314],{"class":296},[36,883,838],{"class":49},[36,885,854],{"class":42},[36,887,888],{"class":38,"line":469},[36,889,154],{"class":42},[36,891,892],{"class":38,"line":490},[36,893,769],{"emptyLinePlaceholder":768},[36,895,896,899,902,905,907],{"class":38,"line":511},[36,897,898],{"class":296},"declare",[36,900,901],{"class":296}," const",[36,903,904],{"class":49}," api",[36,906,314],{"class":296},[36,908,328],{"class":42},[36,910,911,914,916,919,921,923,925,928,931,933,935,938,940,943,945,948,950,952],{"class":38,"line":517},[36,912,913],{"class":303},"  request",[36,915,314],{"class":296},[36,917,918],{"class":42}," \u003C",[36,920,781],{"class":303},[36,922,478],{"class":296},[36,924,786],{"class":49},[36,926,927],{"class":42},">(",[36,929,930],{"class":310},"options",[36,932,314],{"class":296},[36,934,648],{"class":303},[36,936,937],{"class":42},") ",[36,939,456],{"class":296},[36,941,942],{"class":303}," Promise",[36,944,705],{"class":42},[36,946,947],{"class":303},"ApiResponse",[36,949,705],{"class":42},[36,951,781],{"class":303},[36,953,954],{"class":42},">>\n",[36,956,957],{"class":38,"line":526},[36,958,154],{"class":42},[10,960,961,962,965,966,969],{},"With this, you should be able to write code against the API. By reading the ",[33,963,964],{},"ApiRequestOptions"," interface, we clearly understand that we are doing no more than wrapping ",[33,967,968],{},"fetch",". The parameters are nearly the same, only simplified to reveal the necessary information to the model. For the response, we do the heavy lifting to reduce the model's work.",[10,971,972],{},"And finally, the description provides a small example of how to use the tool.",[25,974,976],{"className":286,"code":975,"filename":629,"language":289,"meta":31,"style":31},"async () => {\n  const response = await api.request({\n    method: 'GET',\n    path: '\u002Fproducts',\n    query: { 'status:eq': 'active', '_per_page': 5 }\n  })\n\n  return response.result.map(product => ({\n    id: product.id,\n    name: product.name,\n    status: product.status\n  }))\n}\n",[33,977,978,990,1010,1020,1030,1056,1061,1065,1087,1092,1097,1102,1107],{"__ignoreMap":31},[36,979,980,983,986,988],{"class":38,"line":39},[36,981,982],{"class":296},"async",[36,984,985],{"class":42}," () ",[36,987,456],{"class":296},[36,989,328],{"class":42},[36,991,992,995,998,1000,1002,1005,1008],{"class":38,"line":46},[36,993,994],{"class":296},"  const",[36,996,997],{"class":49}," response",[36,999,478],{"class":296},[36,1001,481],{"class":296},[36,1003,1004],{"class":42}," api.",[36,1006,1007],{"class":303},"request",[36,1009,382],{"class":42},[36,1011,1012,1015,1018],{"class":38,"line":151},[36,1013,1014],{"class":42},"    method: ",[36,1016,1017],{"class":56},"'GET'",[36,1019,183],{"class":42},[36,1021,1022,1025,1028],{"class":38,"line":186},[36,1023,1024],{"class":42},"    path: ",[36,1026,1027],{"class":56},"'\u002Fproducts'",[36,1029,183],{"class":42},[36,1031,1032,1035,1038,1040,1043,1045,1048,1050,1053],{"class":38,"line":199},[36,1033,1034],{"class":42},"    query: { ",[36,1036,1037],{"class":56},"'status:eq'",[36,1039,53],{"class":42},[36,1041,1042],{"class":56},"'active'",[36,1044,710],{"class":42},[36,1046,1047],{"class":56},"'_per_page'",[36,1049,53],{"class":42},[36,1051,1052],{"class":49},"5",[36,1054,1055],{"class":42}," }\n",[36,1057,1058],{"class":38,"line":212},[36,1059,1060],{"class":42},"  })\n",[36,1062,1063],{"class":38,"line":225},[36,1064,769],{"emptyLinePlaceholder":768},[36,1066,1067,1070,1073,1076,1078,1081,1084],{"class":38,"line":238},[36,1068,1069],{"class":296},"  return",[36,1071,1072],{"class":42}," response.result.",[36,1074,1075],{"class":303},"map",[36,1077,307],{"class":42},[36,1079,1080],{"class":310},"product",[36,1082,1083],{"class":296}," =>",[36,1085,1086],{"class":42}," ({\n",[36,1088,1089],{"class":38,"line":247},[36,1090,1091],{"class":42},"    id: product.id,\n",[36,1093,1094],{"class":38,"line":258},[36,1095,1096],{"class":42},"    name: product.name,\n",[36,1098,1099],{"class":38,"line":264},[36,1100,1101],{"class":42},"    status: product.status\n",[36,1103,1104],{"class":38,"line":430},[36,1105,1106],{"class":42},"  }))\n",[36,1108,1109],{"class":38,"line":436},[36,1110,154],{"class":42},[1112,1113,1114,1115,1114,1124],"figure",{},"\n  ",[1116,1117,1118,1119,1114],"video",{"autoPlay":768,"loop":768,"muted":768,"playsInline":768},"\n    ",[1120,1121],"source",{"src":1122,"type":1123},"https:\u002F\u002Fimages.soubiran.dev\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters\u002Fexecute-api-request.mp4","video\u002Fmp4",[1125,1126,1127],"figcaption",{},"Executing an API request and returning only the selected product fields.",[17,1129,1131],{"id":1130},"code-mode-or-simple-tool-call","Code Mode or simple tool call",[10,1133,1134],{},"You may ask yourself, why not just provide a simple tool call to the model, like we did for most MCPs? For example, we could imagine a tool named \"list_returns\" that would take a seller ID and return the list of returns. The model would just need to call this tool with the right parameters, and it would get the result.",[10,1136,1137],{},"You are right. We could have done that. But if you have 150 endpoints, it means having 150 tools. You could reduce that number by grouping some endpoints and using a parameter, similar to GitHub's MCP. For example, their tool \"pull_request_read\" has a \"method\" parameter that can take the values \"get\", \"get_diff\", \"get_status\", \"get_files\", \"get_commits\", \"get_review_comments\", \"get_reviews\", \"get_comments\", and \"get_check_runs\". I will let you imagine the complexity under the hood to make this work and the headache of grouping them. If they add a new method to GitHub tomorrow, they have to update their MCP.",[10,1139,1140],{},"Also, Code Mode allows the model to shape the input and output of the request as needed. For example, if the model knows that the endpoint is very verbose, it can choose to return only the fields it needs. It can also chain requests, create loops, use if\u002Felse statements, retry if the output is not what it expects, and so on. The model is free to orchestrate the request as it wants.",[25,1142,1144],{"className":286,"code":1143,"filename":629,"language":289,"meta":31,"style":31},"async () => {\n  const sellers = (await api.request({\n    method: 'GET',\n    path: '\u002Fsellers',\n    query: { 'status:eq': 'active', '_per_page': 5 }\n  })).result\n\n  const results = []\n\n  for (const seller of sellers) {\n    const products = (await api.request({\n      method: 'GET',\n      path: '\u002Fproducts',\n      query: {\n        sellerId: seller.id,\n        _embed: 'variants',\n        _per_page: 10\n      }\n    })).result\n\n    for (const product of products) {\n      for (const variant of product.variants ?? []) {\n        results.push({\n          seller: seller.name,\n          product: product.name,\n          sku: variant.sku\n        })\n      }\n    }\n  }\n\n  return results\n}\n",[33,1145,1146,1156,1177,1185,1194,1214,1219,1223,1235,1239,1258,1278,1287,1296,1301,1306,1316,1324,1328,1333,1337,1354,1377,1387,1392,1397,1402,1407,1412,1417,1422,1427,1435],{"__ignoreMap":31},[36,1147,1148,1150,1152,1154],{"class":38,"line":39},[36,1149,982],{"class":296},[36,1151,985],{"class":42},[36,1153,456],{"class":296},[36,1155,328],{"class":42},[36,1157,1158,1160,1163,1165,1168,1171,1173,1175],{"class":38,"line":46},[36,1159,994],{"class":296},[36,1161,1162],{"class":49}," sellers",[36,1164,478],{"class":296},[36,1166,1167],{"class":42}," (",[36,1169,1170],{"class":296},"await",[36,1172,1004],{"class":42},[36,1174,1007],{"class":303},[36,1176,382],{"class":42},[36,1178,1179,1181,1183],{"class":38,"line":151},[36,1180,1014],{"class":42},[36,1182,1017],{"class":56},[36,1184,183],{"class":42},[36,1186,1187,1189,1192],{"class":38,"line":186},[36,1188,1024],{"class":42},[36,1190,1191],{"class":56},"'\u002Fsellers'",[36,1193,183],{"class":42},[36,1195,1196,1198,1200,1202,1204,1206,1208,1210,1212],{"class":38,"line":199},[36,1197,1034],{"class":42},[36,1199,1037],{"class":56},[36,1201,53],{"class":42},[36,1203,1042],{"class":56},[36,1205,710],{"class":42},[36,1207,1047],{"class":56},[36,1209,53],{"class":42},[36,1211,1052],{"class":49},[36,1213,1055],{"class":42},[36,1215,1216],{"class":38,"line":212},[36,1217,1218],{"class":42},"  })).result\n",[36,1220,1221],{"class":38,"line":225},[36,1222,769],{"emptyLinePlaceholder":768},[36,1224,1225,1227,1230,1232],{"class":38,"line":238},[36,1226,994],{"class":296},[36,1228,1229],{"class":49}," results",[36,1231,478],{"class":296},[36,1233,1234],{"class":42}," []\n",[36,1236,1237],{"class":38,"line":247},[36,1238,769],{"emptyLinePlaceholder":768},[36,1240,1241,1244,1246,1249,1252,1255],{"class":38,"line":258},[36,1242,1243],{"class":296},"  for",[36,1245,1167],{"class":42},[36,1247,1248],{"class":296},"const",[36,1250,1251],{"class":49}," seller",[36,1253,1254],{"class":296}," of",[36,1256,1257],{"class":42}," sellers) {\n",[36,1259,1260,1263,1266,1268,1270,1272,1274,1276],{"class":38,"line":264},[36,1261,1262],{"class":296},"    const",[36,1264,1265],{"class":49}," products",[36,1267,478],{"class":296},[36,1269,1167],{"class":42},[36,1271,1170],{"class":296},[36,1273,1004],{"class":42},[36,1275,1007],{"class":303},[36,1277,382],{"class":42},[36,1279,1280,1283,1285],{"class":38,"line":430},[36,1281,1282],{"class":42},"      method: ",[36,1284,1017],{"class":56},[36,1286,183],{"class":42},[36,1288,1289,1292,1294],{"class":38,"line":436},[36,1290,1291],{"class":42},"      path: ",[36,1293,1027],{"class":56},[36,1295,183],{"class":42},[36,1297,1298],{"class":38,"line":442},[36,1299,1300],{"class":42},"      query: {\n",[36,1302,1303],{"class":38,"line":461},[36,1304,1305],{"class":42},"        sellerId: seller.id,\n",[36,1307,1308,1311,1314],{"class":38,"line":469},[36,1309,1310],{"class":42},"        _embed: ",[36,1312,1313],{"class":56},"'variants'",[36,1315,183],{"class":42},[36,1317,1318,1321],{"class":38,"line":490},[36,1319,1320],{"class":42},"        _per_page: ",[36,1322,1323],{"class":49},"10\n",[36,1325,1326],{"class":38,"line":511},[36,1327,514],{"class":42},[36,1329,1330],{"class":38,"line":517},[36,1331,1332],{"class":42},"    })).result\n",[36,1334,1335],{"class":38,"line":526},[36,1336,769],{"emptyLinePlaceholder":768},[36,1338,1339,1342,1344,1346,1349,1351],{"class":38,"line":533},[36,1340,1341],{"class":296},"    for",[36,1343,1167],{"class":42},[36,1345,1248],{"class":296},[36,1347,1348],{"class":49}," product",[36,1350,1254],{"class":296},[36,1352,1353],{"class":42}," products) {\n",[36,1355,1356,1359,1361,1363,1366,1368,1371,1374],{"class":38,"line":562},[36,1357,1358],{"class":296},"      for",[36,1360,1167],{"class":42},[36,1362,1248],{"class":296},[36,1364,1365],{"class":49}," variant",[36,1367,1254],{"class":296},[36,1369,1370],{"class":42}," product.variants ",[36,1372,1373],{"class":296},"??",[36,1375,1376],{"class":42}," []) {\n",[36,1378,1379,1382,1385],{"class":38,"line":571},[36,1380,1381],{"class":42},"        results.",[36,1383,1384],{"class":303},"push",[36,1386,382],{"class":42},[36,1388,1389],{"class":38,"line":577},[36,1390,1391],{"class":42},"          seller: seller.name,\n",[36,1393,1394],{"class":38,"line":582},[36,1395,1396],{"class":42},"          product: product.name,\n",[36,1398,1399],{"class":38,"line":588},[36,1400,1401],{"class":42},"          sku: variant.sku\n",[36,1403,1404],{"class":38,"line":594},[36,1405,1406],{"class":42},"        })\n",[36,1408,1410],{"class":38,"line":1409},28,[36,1411,514],{"class":42},[36,1413,1415],{"class":38,"line":1414},29,[36,1416,585],{"class":42},[36,1418,1420],{"class":38,"line":1419},30,[36,1421,261],{"class":42},[36,1423,1425],{"class":38,"line":1424},31,[36,1426,769],{"emptyLinePlaceholder":768},[36,1428,1430,1432],{"class":38,"line":1429},32,[36,1431,1069],{"class":296},[36,1433,1434],{"class":42}," results\n",[36,1436,1438],{"class":38,"line":1437},33,[36,1439,154],{"class":42},[10,1441,1442],{},"With direct tool calls, this workflow requires repeated agent round trips: the model receives each result, decides what to do next, and sends another call. Code Mode keeps that control flow, filtering, and result shaping inside the generated program.",[17,1444,1446],{"id":1445},"return-only-whats-useful","Return only what's useful",[10,1448,1449],{},"If we take a step back, this may look over-engineered. Let us compare the two approaches before looking at the token measurements.",[10,1451,1452],{},"The Cloudflare OpenAPI snapshot used in this series is 23,792,523 characters long. Dividing by four gives a rough estimate of 6 million tokens, but token counts vary by model and content.",[1454,1455,1456,1472],"table",{},[1457,1458,1459],"thead",{},[1460,1461,1462,1466,1469],"tr",{},[1463,1464,1465],"th",{},"Concern",[1463,1467,1468],{},"Direct tool calls",[1463,1470,1471],{},"Code Mode",[1473,1474,1475,1487,1498],"tbody",{},[1460,1476,1477,1481,1484],{},[1478,1479,1480],"td",{},"Dependent work",[1478,1482,1483],{},"The model receives each intermediate result before choosing the next call.",[1478,1485,1486],{},"The generated program can pass intermediate values between calls and return only its final projection.",[1460,1488,1489,1492,1495],{},[1478,1490,1491],{},"Large API surface",[1478,1493,1494],{},"The server must expose and document a tool surface the model can select from.",[1478,1496,1497],{},"The model can search a server-side specification and then compose the narrow calls it needs.",[1460,1499,1500,1503,1506],{},[1478,1501,1502],{},"Data shaping",[1478,1504,1505],{},"The model often receives each tool's response before it can reduce it.",[1478,1507,1508],{},"The generated program can filter, aggregate, and project data before returning it.",[10,1510,1511],{},"A carefully designed direct-tool server can also batch data and keep responses compact. Code Mode is most useful when a task needs dependent calls, local processing, or an evolving API surface.",[10,1513,1514],{},"To illustrate, let me ask my agent to list the top 10 most CPU intensive workers:",[1112,1516,1114,1517,1114,1522],{},[1116,1518,1118,1519,1114],{"autoPlay":768,"loop":768,"muted":768,"playsInline":768},[1120,1520],{"src":1521,"type":1123},"https:\u002F\u002Fimages.soubiran.dev\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters\u002Flist-top-cpu-intensive-workers.mp4",[1125,1523,1524],{},"Listing the 10 most CPU-intensive workers with Code Mode.",[10,1526,1527],{},"In this recorded run, the agent used 34k tokens.",[10,1529,1530],{},"In our example, the OpenAPI specification is 89,105 characters long, roughly 22k tokens using the same four-characters-per-token shortcut.",[10,1532,1533],{},"Now, let us try some examples to see how many tokens the model needs with our Code Mode MCP.",[604,1535,1536,1555,1582,1600],{},[607,1537,1538,1539,1545],{},"\"List requested return requests for seller seller-aurora, sorted by most recently updated, returning the first 10 results.\"",[1540,1541,1542],"ul",{},[607,1543,1544],{},"18.1k tokens",[1112,1546,1114,1547,1114,1552],{},[1116,1548,1118,1549,1114],{"autoPlay":768,"loop":768,"muted":768,"playsInline":768},[1120,1550],{"src":1551,"type":1123},"https:\u002F\u002Fimages.soubiran.dev\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters\u002Flist-return-requests.mp4",[1125,1553,1554],{},"Listing return requests for a seller with Code Mode.",[607,1556,1557,1558,1563,1564,1569,1570],{},"\"Create a pending seller named North Star Living with slug north-star-living and email ",[1559,1560,1562],"a",{"href":1561},"mailto:hello@north-star-living.example","hello@north-star-living.example",".\"",[1540,1565,1566],{},[607,1567,1568],{},"16.9k tokens","\n ",[1112,1571,1572,1573,1572,1579,1569],{},"\n   ",[1116,1574,1575,1576,1572],{"autoPlay":768,"loop":768,"muted":768,"playsInline":768},"\n     ",[1120,1577],{"src":1578,"type":1123},"https:\u002F\u002Fimages.soubiran.dev\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters\u002Fcreate-pending-seller.mp4",[1125,1580,1581],{},"Creating a pending seller with Code Mode.",[607,1583,1584,1585,1569,1590],{},"\"Publish product product-desk-lamp by changing its status to active.\"",[1540,1586,1587],{},[607,1588,1589],{},"17.8k tokens",[1112,1591,1572,1592,1572,1597,1569],{},[1116,1593,1575,1594,1572],{"autoPlay":768,"loop":768,"muted":768,"playsInline":768},[1120,1595],{"src":1596,"type":1123},"https:\u002F\u002Fimages.soubiran.dev\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters\u002Fpublish-product.mp4",[1125,1598,1599],{},"Publishing a product with Code Mode.",[607,1601,1602,1603,1569,1608],{},"\"Remove product product-desk-lamp\"",[1540,1604,1605],{},[607,1606,1607],{},"17.5k tokens",[1112,1609,1572,1610,1572,1615,1569],{},[1116,1611,1575,1612,1572],{"autoPlay":768,"loop":768,"muted":768,"playsInline":768},[1120,1613],{"src":1614,"type":1123},"https:\u002F\u002Fimages.soubiran.dev\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters\u002Fremove-product.mp4",[1125,1616,1617],{},"Removing a product with Code Mode.",[10,1619,1620],{},"These measurements are examples from a local fixture. This is not a true benchmark. However, the important thing to keep in mind is that the model does not need the entire API description to interact with the API. It builds its own context from what it needs.",[17,1622,1624],{"id":1623},"to-a-safer-execution","To a safer execution",[10,1626,1627],{},"Great!",[10,1629,1630],{},"We gave the model a tool to search the OpenAPI specification, and now, it can even execute the API calls itself, and return only what matters. But, is it safe?",[10,1632,1633,1634,1637],{},"The model code cannot be trusted. That is the first rule in web security: never trust user input. Here, model-generated code is user input executed by a trusted local evaluator based on the ",[33,1635,1636],{},"Function"," constructor. In the next article, we will see how to make that execution safer with a dedicated environment.",[1639,1640,1641],"style",{},"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":31,"searchDepth":46,"depth":46,"links":1643},[1644,1645,1646,1647,1648],{"id":19,"depth":46,"text":20},{"id":276,"depth":46,"text":277},{"id":1130,"depth":46,"text":1131},{"id":1445,"depth":46,"text":1446},{"id":1623,"depth":46,"text":1624},"1d7b5e93-6a24-4f80-bc19-3e8d0a572f16","2026-07-12","Use a host-owned API request helper to validate and execute a narrow API call, then return only the useful projection.","md",{"branch":1654},"part-4-local-execute",null,{},"\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters","---\ncontentId: 1d7b5e93-6a24-4f80-bc19-3e8d0a572f16\npart: 4\ntitle: Calling APIs with Code Mode and Returning Only What Matters\ndescription: Use a host-owned API request helper to validate and execute a narrow API call, then return only the useful projection.\ngithub:\n  branch: part-4-local-execute\ndate: 2026-07-12\nseriesSlug: building-code-mode-for-apis-with-mcp-and-isolated-workers\n---\n\nWe have seen how to let the model write JavaScript code to search an OpenAPI specification that is larger than the context window. The specification can grow over time, although the runtime still has practical limits on execution time, memory, and returned data.\n\nNow, we'll see how to let the model write JavaScript to interact with our API, based on the knowledge it has gathered from the OpenAPI specification.\n\n## Our MCP needs a second tool\n\nOur goal was to create a system that makes interactions between the LLM and our API easier. For now, our LLM can retrieve and understand the API surface:\n\n```json [LLM Tool Call]\n{\n  \"code\": \"async () => {\\n  const results = [];\\n  for (const [path, methods] of Object.entries(spec.paths)) {\\n    for (const [method, operation] of Object.entries(methods)) {\\n      if (operation?.tags?.some(tag => tag.toLowerCase() === 'returns')) {\\n        results.push({\\n          method: method.toUpperCase(),\\n          path,\\n          operationId: operation.operationId,\\n          summary: operation.summary,\\n          description: operation.description,\\n          parameters: operation.parameters,\\n          requestBody: operation.requestBody,\\n        });\\n      }\\n    }\\n  }\\n  return results;\\n}\"\n}\n```\n\n```json [LLM Tool Output]\n[\n  {\n    \"method\": \"GET\",\n    \"path\": \"\u002Freturns\",\n    \"operationId\": \"listReturns\",\n    \"summary\": \"List return requests\",\n    \"description\": \"List return requests, optionally narrowed to an order, order item, seller, or return status.\",\n    \"parameters\": [],\n    \"requestBody\": null\n  }\n]\n```\n\nHowever, it cannot interact with it.\n\nTo do so, we need to provide it with a second tool: the executor.\n\n## The executor tool\n\nThe executor tool completes the duo of the search tool. Under the hood, it is a wrapper around a pre-configured API client, a fetch function in our case, that will allow the model to call the API using the information it has gathered from the OpenAPI specification.\n\nAt a high level, it is very similar to the search tool, with the same idea of providing the model with a pre-configured playground to write code against a predefined typed API. The model is responsible for orchestrating one or multiple requests, depending on the complexity of the task, and returning only what matters.\n\n```typescript [executor.ts]\nexport function registerExecuteTool(server: McpServer): void {\n  server.registerTool(\n    'execute',\n    {\n      title: 'MarketHub API Code Executor',\n      description: '...',\n      inputSchema: z.object({\n        code: z\n          .string()\n          .max(MAX_CODE_LENGTH)\n          .describe('An async arrow function that executes a MarketHub API request')\n      }),\n    },\n    async ({ code }) => {\n      try {\n        const result = await evaluateExecuteCode(code)\n        return { content: [{ type: 'text', text: formatExecuteResult(result) }] }\n      }\n      catch (error) {\n        return {\n          content: [{ type: 'text', text: `Execute failed: ${errorMessage(error)}` }],\n          isError: true\n        }\n      }\n    }\n  )\n}\n```\n\nAs you can see, the similarity with the search tool is obvious. We take a JavaScript arrow function as input, evaluate it, and return the result.\n\nTwo important differences to note:\n\n1. The description is shaped to make the model understand that it can write code against the API, and that it should return only what matters.\n2. We use `evaluateExecuteCode` instead of `evaluateSearchCode`. At their core, both evaluate code, but the data provided in the context is different.\n\nThe description starts by explaining succinctly what the tool does.\n\n```text [Example]\nExecute JavaScript code against the local MarketHub API.\n\nFirst use the 'search' tool to find the right endpoint, method, parameters, and request body, then write code using api.request().\n```\n\nThen, the description provides a TypeScript interface to give the model complete knowledge of how to write code.\n\n```typescript [Example]\ninterface ApiRequestOptions {\n  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'\n  path: string\n  query?: Record\u003Cstring, string | number | boolean | undefined>\n  body?: unknown\n  contentType?: string\n  rawBody?: boolean\n}\n\ninterface ApiResponse\u003CT = unknown> {\n  success: boolean\n  status: number\n  result: T\n  errors: Array\u003C{ code: string | number, message: string }>\n  messages: Array\u003C{ code: string | number, message: string }>\n}\n\ndeclare const api: {\n  request: \u003CT = unknown>(options: ApiRequestOptions) => Promise\u003CApiResponse\u003CT>>\n}\n```\n\nWith this, you should be able to write code against the API. By reading the `ApiRequestOptions` interface, we clearly understand that we are doing no more than wrapping `fetch`. The parameters are nearly the same, only simplified to reveal the necessary information to the model. For the response, we do the heavy lifting to reduce the model's work.\n\nAnd finally, the description provides a small example of how to use the tool.\n\n```typescript [Example]\nasync () => {\n  const response = await api.request({\n    method: 'GET',\n    path: '\u002Fproducts',\n    query: { 'status:eq': 'active', '_per_page': 5 }\n  })\n\n  return response.result.map(product => ({\n    id: product.id,\n    name: product.name,\n    status: product.status\n  }))\n}\n```\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\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters\u002Fexecute-api-request.mp4\" type=\"video\u002Fmp4\">\n  \u003C\u002Fvideo>\n  \u003Cfigcaption>Executing an API request and returning only the selected product fields.\u003C\u002Ffigcaption>\n\u003C\u002Ffigure>\n\n## Code Mode or simple tool call\n\nYou may ask yourself, why not just provide a simple tool call to the model, like we did for most MCPs? For example, we could imagine a tool named \"list_returns\" that would take a seller ID and return the list of returns. The model would just need to call this tool with the right parameters, and it would get the result.\n\nYou are right. We could have done that. But if you have 150 endpoints, it means having 150 tools. You could reduce that number by grouping some endpoints and using a parameter, similar to GitHub's MCP. For example, their tool \"pull_request_read\" has a \"method\" parameter that can take the values \"get\", \"get_diff\", \"get_status\", \"get_files\", \"get_commits\", \"get_review_comments\", \"get_reviews\", \"get_comments\", and \"get_check_runs\". I will let you imagine the complexity under the hood to make this work and the headache of grouping them. If they add a new method to GitHub tomorrow, they have to update their MCP.\n\nAlso, Code Mode allows the model to shape the input and output of the request as needed. For example, if the model knows that the endpoint is very verbose, it can choose to return only the fields it needs. It can also chain requests, create loops, use if\u002Felse statements, retry if the output is not what it expects, and so on. The model is free to orchestrate the request as it wants.\n\n```typescript [Example]\nasync () => {\n  const sellers = (await api.request({\n    method: 'GET',\n    path: '\u002Fsellers',\n    query: { 'status:eq': 'active', '_per_page': 5 }\n  })).result\n\n  const results = []\n\n  for (const seller of sellers) {\n    const products = (await api.request({\n      method: 'GET',\n      path: '\u002Fproducts',\n      query: {\n        sellerId: seller.id,\n        _embed: 'variants',\n        _per_page: 10\n      }\n    })).result\n\n    for (const product of products) {\n      for (const variant of product.variants ?? []) {\n        results.push({\n          seller: seller.name,\n          product: product.name,\n          sku: variant.sku\n        })\n      }\n    }\n  }\n\n  return results\n}\n```\n\nWith direct tool calls, this workflow requires repeated agent round trips: the model receives each result, decides what to do next, and sends another call. Code Mode keeps that control flow, filtering, and result shaping inside the generated program.\n\n## Return only what's useful\n\nIf we take a step back, this may look over-engineered. Let us compare the two approaches before looking at the token measurements.\n\nThe Cloudflare OpenAPI snapshot used in this series is 23,792,523 characters long. Dividing by four gives a rough estimate of 6 million tokens, but token counts vary by model and content.\n\n| Concern | Direct tool calls | Code Mode |\n| --- | --- | --- |\n| Dependent work | The model receives each intermediate result before choosing the next call. | The generated program can pass intermediate values between calls and return only its final projection. |\n| Large API surface | The server must expose and document a tool surface the model can select from. | The model can search a server-side specification and then compose the narrow calls it needs. |\n| Data shaping | The model often receives each tool's response before it can reduce it. | The generated program can filter, aggregate, and project data before returning it. |\n\nA carefully designed direct-tool server can also batch data and keep responses compact. Code Mode is most useful when a task needs dependent calls, local processing, or an evolving API surface.\n\nTo illustrate, let me ask my agent to list the top 10 most CPU intensive workers:\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\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters\u002Flist-top-cpu-intensive-workers.mp4\" type=\"video\u002Fmp4\">\n  \u003C\u002Fvideo>\n  \u003Cfigcaption>Listing the 10 most CPU-intensive workers with Code Mode.\u003C\u002Ffigcaption>\n\u003C\u002Ffigure>\n\nIn this recorded run, the agent used 34k tokens.\n\nIn our example, the OpenAPI specification is 89,105 characters long, roughly 22k tokens using the same four-characters-per-token shortcut.\n\nNow, let us try some examples to see how many tokens the model needs with our Code Mode MCP.\n\n1. \"List requested return requests for seller seller-aurora, sorted by most recently updated, returning the first 10 results.\"\n\n   - 18.1k tokens\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\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters\u002Flist-return-requests.mp4\" type=\"video\u002Fmp4\">\n     \u003C\u002Fvideo>\n     \u003Cfigcaption>Listing return requests for a seller with Code Mode.\u003C\u002Ffigcaption>\n   \u003C\u002Ffigure>\n\n2. \"Create a pending seller named North Star Living with slug north-star-living and email hello@north-star-living.example.\"\n\n    - 16.9k tokens\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\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters\u002Fcreate-pending-seller.mp4\" type=\"video\u002Fmp4\">\n      \u003C\u002Fvideo>\n      \u003Cfigcaption>Creating a pending seller with Code Mode.\u003C\u002Ffigcaption>\n    \u003C\u002Ffigure>\n\n3. \"Publish product product-desk-lamp by changing its status to active.\"\n\n    - 17.8k tokens\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\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters\u002Fpublish-product.mp4\" type=\"video\u002Fmp4\">\n      \u003C\u002Fvideo>\n      \u003Cfigcaption>Publishing a product with Code Mode.\u003C\u002Ffigcaption>\n    \u003C\u002Ffigure>\n\n4. \"Remove product product-desk-lamp\"\n\n    - 17.5k tokens\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\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters\u002Fremove-product.mp4\" type=\"video\u002Fmp4\">\n      \u003C\u002Fvideo>\n      \u003Cfigcaption>Removing a product with Code Mode.\u003C\u002Ffigcaption>\n    \u003C\u002Ffigure>\n\nThese measurements are examples from a local fixture. This is not a true benchmark. However, the important thing to keep in mind is that the model does not need the entire API description to interact with the API. It builds its own context from what it needs.\n\n## To a safer execution\n\nGreat!\n\nWe gave the model a tool to search the OpenAPI specification, and now, it can even execute the API calls itself, and return only what matters. But, is it safe?\n\nThe model code cannot be trusted. That is the first rule in web security: never trust user input. Here, model-generated code is user input executed by a trusted local evaluator based on the `Function` constructor. In the next article, we will see how to make that execution safer with a dedicated environment.\n",{"title":5,"description":1651},"building-code-mode-for-apis-with-mcp-and-isolated-workers",{"loc":1657},"series\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters","YJz-3pALuFR9wNWosuAdefBlvvsDEFUe77GN3FitHg8",{"overview":1665,"chapters":1832},{"id":1666,"title":1667,"body":1668,"contentId":1813,"date":1650,"description":1814,"extension":1652,"github":1815,"meetTheInstructor":1816,"meta":1817,"navigation":768,"part":1655,"path":1818,"rawbody":1819,"robots":1655,"schemaOrg":1655,"seo":1820,"seriesSlug":1660,"sitemap":1821,"stem":1822,"subtitle":1823,"topics":1824,"__hash__":1831},"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":1669,"toc":1810},[1670,1673,1681,1687,1700,1716,1719,1722,1725,1781,1789,1800,1804],[10,1671,1672],{},"Hello and welcome! 👋",[10,1674,1675,1676,1680],{},"This series is a practical follow-up to ",[1559,1677,1679],{"href":1678},"\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,1682,1683,1684,1686],{},"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 ",[33,1685,1636],{}," 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,1688,1689,1690,1694,1695,1699],{},"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 ",[1559,1691,1693],{"href":1692},"\u002Fseries\u002Fai-agents-and-mcp-server-teaming-up-for-the-agentic-web","AI Agents and MCP Server: Teaming Up for the Agentic Web",", especially ",[1559,1696,1698],{"href":1697},"\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,1701,1702,1703,1707,1708,1711,1712,1715],{},"Throughout the series, the ",[1704,1705,1706],"strong",{},"model"," generates tool calls or code, the ",[1704,1709,1710],{},"MCP client"," (or agent) runs the model loop, and the ",[1704,1713,1714],{},"MCP server"," provides the capabilities. Keeping these roles separate is important: the host, not generated code, defines which capabilities are available.",[10,1717,1718],{},"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,1720,1721],{},"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,1723,1724],{},"Throughout this journey, we will:",[604,1726,1727,1737,1752,1762,1775],{},[607,1728,1729,1732,1733,1736],{},[1704,1730,1731],{},"Beyond One Tool Call at a Time: Introducing Code Mode",": Build two direct ",[33,1734,1735],{},"Drive"," tools over a Markdown fixture and observe how the complete file content travels through the model's context before the next tool call.",[607,1738,1739,1742,1743,1745,1746,1748,1749,1751],{},[1704,1740,1741],{},"Let the Model Orchestrate Tools with a Local Code Runtime",": Replace the two direct tools with one generic ",[33,1744,33],{}," tool, expose a typed ",[33,1747,1735],{}," facade, and introduce the executor interface that later parts will replace. The local evaluator based on the ",[33,1750,1636],{}," constructor is intentionally a trusted development shortcut, not a production sandbox.",[607,1753,1754,1757,1758,1761],{},[1704,1755,1756],{},"Searching OpenAPI Specifications Without Filling Context",": Keep the OpenAPI document inside the server, resolve its local ",[33,1759,1760],{},"$ref"," values, and let generated code search a compact type facade instead of returning the complete specification to the model.",[607,1763,1764,1766,1767,1770,1771,1774],{},[1704,1765,5],{},": Add a separate ",[33,1768,1769],{},"execute"," tool with a host-owned ",[33,1772,1773],{},"api.request()"," helper. We will validate request options, call the local MarketHub fixture, and return a narrow projection rather than the complete API response.",[607,1776,1777,1780],{},[1704,1778,1779],{},"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,1782,1783,1784,1788],{},"The companion repository, ",[1785,1786],"git-hub-link",{"repo":1787},"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.",[1790,1791,1794],"callout",{"color":1792,"icon":1793},"info","i-ph-info-duotone",[10,1795,1796,1797,1799],{},"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 ",[33,1798,1636],{}," constructor for development, while Part 5 provides a Cloudflare deployment scaffold and structural security evaluation.",[17,1801,1803],{"id":1802},"chapters","Chapters",[1805,1806],"series-chapters-list",{"className":1807},[1808,1809],"mx-auto","max-w-5xl",{"title":31,"searchDepth":46,"depth":46,"links":1811},[1812],{"id":1802,"depth":46,"text":1803},"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":1471,"repository":1787},"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":1667,"description":1814},{"loc":1818},"series\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers","Build a context-efficient MCP server for OpenAPI-described APIs",[1825,1826,1827,1828,1829,1830,289],"ai","ai-agents","mcp","code-mode","openapi","cloudflare","WgDRYOu5CDIYY78O1GSEOv6BKbIsrTVwVf8cTOkdsOA",[1833,1839,1845,1851,1853],{"contentId":1834,"title":1731,"description":1835,"path":1836,"part":39,"github":1837,"topics":1655},"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":1838},"part-1-direct-tools",{"contentId":1840,"title":1741,"description":1841,"path":1842,"part":46,"github":1843,"topics":1655},"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":1844},"part-2-generic-code-mode",{"contentId":1846,"title":1756,"description":1847,"path":1848,"part":151,"github":1849,"topics":1655},"8c4a1e72-bf39-4d65-a08e-2c7f91b6d543","Keep an OpenAPI specification server-side and search a compact typed facade without returning the complete document.","\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fsearching-openapi-specification-without-filling-the-context",{"branch":1850},"part-3-search",{"contentId":1649,"title":5,"description":1651,"path":1657,"part":186,"github":1852,"topics":1655},{"branch":1654},{"contentId":1854,"title":1779,"description":1855,"path":1856,"part":199,"github":1857,"topics":1655},"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":1858},"part-5-dynamic-workers",1795016691580]