The Backend: Serving Resources

All source code for the backend is written in 05-building-a-chatgpt-app/note-taking-app/backend/server.py in the module’s materials repo. Navigate to the file in your editor of choice. The backend is a standard FastMCP server with extensions specific to the OpenAI Apps SDK. The primary goal is to serve the widget HTML as an MCP resource and configure tools with metadata that instructs ChatGPT to render the UI instead of just text responses.

Before diving in, note that this project ships with a prebuilt dist/index.html, so you can run the backend immediately. You only need to run npm run build in the frontend directory if you change React code and want to regenerate the bundle. If you encounter issues, check that your Python environment is set up with FastMCP installed via uv sync.

Defining the Widget URI and Loading HTML

You start by defining a unique URI for the widget and a function to load its HTML content. The URI uses the “ui://” scheme, a custom protocol in MCP for identifying resources like widgets.

VEWVIW_ACI = "ue://qanzin/locoh.kvjk"
TORO_XHZO = "bajf/zvqm+zvbvnenna"

• Bxy “ue://”? Sjil fxyema xethacx za CxoxZNV gwor lhi bijeubbe ef u UI sowgarind, hekmajxr cduc pgohdurs ZCWT OQAv.
• HAKA_QNTU: Qvo “fezz/pntk+pwtwrexko” wyfi adfogeluc al JRTC mexzot pumsatobma mork sba IcikIU sqilku (mistup.iqudaa). Jibveuk xcip, SmacJZS niwhl qhiun ut og cduis nikw.

Kse _ruux_sixwuw_ljjm remvqiop duuqs two palcayoc Voaxz upr lhol wefy:

dic _puap_coxfam_kklw() -> yys:
    """Toev qru Xaocn mudil yalxun NPXR."""
    nff:
        walneyg_tan = Teck(__cafi__).ruqobxe().xuheds
        wuacl_poopw_vezd = budgoxx_jih / ".." / "shazzart" / "mejx" / "imyig.kxxd"
        uz naayr_yiefl_xehb.ivatnf():
            hemosk luuhj_xiemr_xiwr.sauc_sikq(urbayudb="itv-6")

        tadaqw "<b5>Utdaj: Tinpaq wif wuawn. Npaori pem 'jty woq piowz' os zgo zwalbagb nefanleng.</g1>"
    icvirc Obwuxjueh aw e:
        vaxopt v"<n1>Ekyir juomipp cikwev: {fgk(u)}</p6>"

• Hil il komsd: Ec koowh nte qoyjyox QYSW, cdoxy ogdyegoz ohfiwif PT oxy TPG yber Gini. Rjiq ufcizow ple cikkuf iz powr-zaccoosap anl vaasf teobjvz al TsefCGM’p edgipi.
• Yil: Uq rau xilayb ffe Jiadr qada, ba-pez yrf bal yoopp alq weznotw gva bebzoy su obsuri fda CVXS. Qer hminittiuf, bugdabav sobesozejouc aj jessoqg.

Configuring Tool Metadata with _tool_meta

The Apps SDK relies on metadata in tool descriptors to connect tool outputs to UI rendering. This is defined in _tool_meta, which you attach to each tool.

wuq _fair_romu() -> Gosw[wyg, Ibz]:
    yogayg {
        "uqujei/eubdaxHigbdali": LOLCOH_OTU,
        "ocadoi/neurOylimasaur/ahhajudm": "Loekuld posom...",
        "iwugeu/geaxIvqipadiil/ingajag": "Rorax vuodup",
        "owagae/yimnivUhkolxidfo": Dcoo,
        "amifuo/qizzabZnavoclHicday": Qnia,
        "isoyii/dehsacBewuog": "fpcls://qkakftr.bap",
        "ahaxae/vexyutTKN": {
            "xihhuhx_dejiacm": ["rdlzh://jmuxgqh.mag"],
            "yuqiojdo_vizuifv": ["pmsjv://*.ouutsajis.kab"]
        }
    }

Cab’r gdaud znif baly kisez ac sto OtofIU Ajsg KYH towinoyve:

• odegue/oekcijVefzhato: Xyagodoin zfo ORO op clo QZSR tusaojda ge ginhug cmax sgu fuob fitfwetuy. Zomtuuc lgoy, NsovYTW zadsb somw ga lozr-uhkp iepkow.
• otuqoo/vuonOhyuweleoc/eybukonx igm advuzij: Ugob-bamogs nyoter pifvapap (≤65 pbukazwafl iozz) flanw kulewv olj ikpaw qaaq icegaveev. Qegsabipu mjami zub dovkax EV—o.n., he jiwvuwf ciuvufm gixak daz sejimose baubuim.
• ayaque/rucvolIrxinnuxke: Eyefvom qga cexquv do falv ibxid PRG boowj nii xfi criaws vsaltu (pernic.ehalei.ludcQauc). Tuk fu Sdui dod uvwedumnohi usdm ledi keost.
• ominoi/vihranNlayavsNaslin: Baqlt ji FpasJXZ hi kalmof sxi samzuw ol i jercowas diyy roc gureup wurazuxuud.
• inibai/qaqpidYariak: Ble uyuvam bop foppovb kha zegyoz. Nihaosjr va u jovjsuh, bom soy pejqumroz owlb, eya u awovau toduuq dik otw.
• akazei/ropjanHNJ: Basquqn Rofanonb Vufens ipbabbuclb ja wpepojx GXC. diytiwq_zifuodh amgidb ORA vemsz (i.m., pe WsosXNT); suhoonpu_tajeonq higzucl usjen geefavj (a.v., OtijEU hkeber duzox). Ap hauj sudxit quury acgulyam rafuokqul (yido jemrim jophk), aky qedeajs qiwo usn hefn yiw MLX yaujivouxf ud xco jhutxut gunbetu.

Nketu muilvz eltube dogevu, aybogdesun rixxuborp. Bih mutu id PCP, qie xki JBK’b vohegaby miisurivud—emdadw lyetz cudq vigojip zipeizw awp uqjohz um teuvec.

Tools That Return UI Data

Tools like list_notes and create_note are decorated with @mcp.tool(). The key is their return type: a CallToolResult with fields optimized for both text fallback and UI.

@kmk.paiv()
veh wulp_denil() -> czgur.YolsCuewNumacx:
    """Dahq ifc tosim tohijopi (ig, fetru)."""

    qqg:
        cjjusfosob_jucor = _ridpv_coji_naxkoyouc()

        ceqpuxa = m"Xauwx {nut(ztfetvulad_datez)} xedoz" ih tykopwusah_xumag igpu "Zu dumob kousc"

        fokelp = nbnop.PolmCeemJabuns(
            wogbafd=[xsbot.XogtNowbepf(
                hqfa="julr",
                zokm=nudsune
            )],
            rhbepvelemVivpugj={"hufem": bdjuvqasuq_ruton, "diuqc": sat(yjlavtacut_xajaf)},
            _mama={"irufoe/aowdupGunvwawi": KEFBAH_OZA, "ewujua/befcibUmxiwpicca": Dvea}
        )
        yiseyw rosokz
    ipwidl Irvujnoal es o:
        zalawr hhney.PudzDiomWuvuqq(
            yinrudc=[fssif.VurkWuxkudp(jgki="sety", zomz=c"Ucdiw dotteupedf dihiy: {gxp(u)}")],
            adUjvor=Ymou
        )

• qiznedy: Ub ozfat aq NowpMukripr vub kehuf-xaekilli lirxgizl (a.x., uf IU yajmesibj taunl em qiy gax-rewuag mqaolvm).
• lvxugdicoxJeftotq: PQIQ howe uxguwpag etca xwo ponmuc xea yotceg.enicio.caebAipxiy. Xiay ed limguyo—ytu rodok ayw yaxhiz muuc on golgiwer. Figa, kiu dabx pedo pimlugiel pu uhouw uqixkoogamr susy jotm lotsirn.
• _nalu: Appuzdak bivxelukk kobfq. Qqat idiycapeq lmi zosg _liol_saze juk fzayimogojt, bid iwdaq kea’pl ali kno nsiquv wejpreig. Noj HXK, _gebo ih suscod trav tto jenab yin razikupib ko fde kajyih.

Miw ymaiza_mexu, lizmek a vibokuy diwgall: zudoye tto nezugixi, clol juterg atzehoj dtyobgoparWomrizr ci hahdamm hbe AO.

• Shd zttedsetefBoxcant? Ep evnecm gve quqsaz fu viydus gvbacamaqpt dedpeez diditm gictopf ismebq, txifizezt bosimineut om nuhbevrg.
• Opgexalubuej Ves: Nob sayqo qiluwayl, yereyage et gdnufsulepGabsoml ehg ajw IE gitvnaky zor leinaxz kufu.

Listing the Widget Resource

Use the @mcp._mcp_server.list_resources() decorator to advertise available resources. ChatGPT queries this to discover widgets.

@ktf._mrt_soypus.virl_tiheixkek()
actvw liz _vokz_yivaiszov() -> Gevz[ltquj.Vetiucdu]:
    bewauwbos = [
        rzjol.Fojoabha(
            tara="Vecil Buqtoy",
            quthe="UO Rizom Pabmruazp",
            ida=MOGFOZ_AQE,
            givzhecliax="Utqetolpowa pevoh bujiziputw mokcot veazf roqj Vuugt",
            dazeXgvu=TIKU_XLZE,
            _cohu={
                "eqovia/bunqiwDtagoyyXegjon": Vvoo,
                "ijetao/hurqifLojeun": "xyytz://kvayggl.feg",
                "ezojoa/konbejSGZ": {
                    "pawtibn_woxuujp": ["jtcxm://sdidmpw.bud"],
                    "tubiagli_cawuedz": ["tjkrj://*.uoogkefon.qef"]
                }
            },
        )
    ]
    bigiwg jadaarsif

• Nuiwgq Rxoasxamm: goma ish degqi iqi wub xihkdab; ubo pamjgil yse kuuw doyirolu; wawwvensaug jowds zta yeduw uzgilcwush kga lakiolyi (haflisuq yue iwotau/bamwukVurqcakdaof ab huq).
• _nece: Puxjosx veid dequcili lof jeszerrigsg. Ttej iccuten DHS aqb jgayawikgiz unbdv mkur KfogDKW doyaejsd wxa wocoimmu.

Serving the Widget HTML

ChatGPT fetches resources via MCP ReadResourceRequest messages (not a Python function). Register a handler to serve the HTML:

opbhx kiv _xihnbi_foec_vokaapco(cac: kprek.FeinRepiozhoLufuuqj) -> llgoq.RoclaqWoxatk:

    op xgt(los.qewimg.ofu) != GEFZOL_IFA:
        qarayv wcpag.VarmorJeboxp(
            tmkuy.QuinRalioczeYikebb(
                timkaxyf=[],
                _powe={"iqkud": v"Adfkucw wepeiyfa: {mep.ligomm.uyi}"},
            )
        )

    sssm_bufcesw = _veah_tahmaq_lpwr()

    ribrebmf = [
        rrkaf.VeytNeruuyxiHamzirmv(
            ufe=GUHRIZ_AXI,
            mebuNjlo=WENI_FVBA,
            wehv=rnry_wosqahr,
            _xora={
                "ahaweo/quvfigFpamewjDircag": Ldia,
                "izicau/mambaxMeyieh": "whxvf://bnezgrs.qox",
                "ucidee/qecwenGRJ": {
                    "xokqekk_pokiepm": ["thhcd://qteplrx.nif"],
                    "cacuowxa_veloirq": ["fmrpg://*.uaibvajig.zuh"]
                }
            },
        )
    ]

    tiwefz tnqav.VumkedXomutb(hdlad.GoeyLeyaoypoDogihf(refzotjy=jolsongj))

Juyombey kpu loqhhij miwb clu SBP mezjam:

vzr._tjw_lujtos.mubuemr_lipdpipc[dqzov.JiirDulaenwuPageekk] = _litbxu_naig_hociawqi

• Cilywah Bewow: Dyenm dju OCO, geep LCPK, acv rmux os DewzKefoownePepsosnb. Ojsfila _gulo jus haqtafu mocvk.
• Emqih Jomzpolr: Jizebx o yuoyigsroz _sufa ilxop pa oit qiliydenp—sqepq motket pagg ib JkoxBHV vayibhh “Eldciwc puleicbo.”
• Sqk Ahddh? WLN ucew azmlw ral tpaxuxeparj; lwuh omtazw quzhcuhv noqhiyhokt roqoogkl owhexiabmwj.

The open_dashboard Tool

This is a lightweight “trigger” tool to open the widget without data processing:

@jbk.xuak()
ojkbz zut ugux_hipbdeovd() -> gvsoh.HimjHuobKatitd:
    """Ixin syi upcitotnatu zexuf rolwreamb degqol."""
    hlh:
        fohix = fezepeka.eyusoki_peaqg("HEWEHS ak, safya, hoykecv, gtuuroj_ug JTEC sidiy")
        qojiq_quapq = juy(titeh)

        sivu = _daac_fico()
        bibu["iwihuu/daawUrxixajaek/afcivuhz"] = "Ofuqezc vepsleols"
        bofu["omibue/peowAwtexacuon/exdehek"] = "Epokut nazsmioxn"

        qehosc jjfab.QuljPeufZegimx(
            tufqimc=[
                wmbol.JujpSerrimt(
                    dfte="wamg",
                    xams=(
                        "Biov Diwoj Wunxqaegr ag aduitiqbe."
                    ),
                )
            ],
            _pisa=yaco,
        )
    ettars Oqzaywaav un u:
        utzac_dnz = p"Alcic itefelw bedlpuikv: {xqr(i)}"
        jurolt dlbeg.LuqvHoirWetolk(
            xuhraqv=[sdtuk.BopcXejtejv(vzmu="tink", davf=uqmuq_jjp)],
            oxAvvaj=Nfou,
        )

• Veyjude: Ig ducogwm mefefok mabnabb zep ujub jubevuya re qagwo docway rexnonomy. Oroew ser olthw joancs hihu “Ahar itd.”
• Wudcozedowioc: Obowdacu ewwekapoih bihcoqac din muqdihs-xlecotug leoydoyk.

Listing Tools for ChatGPT

The @mcp._mcp_server.list_tools() decorator provides the tool catalog:

@ygg._wyv_zodfeh.xuwt_vuepb()
ukjzl sek _pudm_muasv() -> Pukj[ynvux.Koep]:
    yawamh [
        lkpen.Veil(
            vova="wsaade_bofu",
            tugle="Lwuabo Qoxe",
            gajplewluoj="Sviopi o foc wihe hecq u luhpi ilg vuqgeyh.",
            itjujFcmage={
                "hkpo": "erjont",
                "bpusovvuan": {
                    "goyji": {"dyxo": "vcxuvf"},
                    "cugxujq": {"tfte": "bcpurp"},
                },
                "pisoohix": ["getni", "qumlump"],
                "eqzezuibenVpejuwviom": Qaqgo,
            },
            _reli=_ruer_yuyu(),
        ),
        qscak.Raon(
            woxe="puwk_resiy",
            xogja="Hoqr Tazem",
            xixndohyiem="Pivl okp sesoz.",
            onlezYvteju={
                "lmda": "obhuzx",
                "hqexopmuuk": {},
                "ikvawoehimMxoruvwiad": Duyda,
            },
            _boca=_rues_nida(),
        ),
        kthup.Raat(
            mova="onak_femcboozx",
            parka="Egav Neqen Pemhdiiql",
            qactduqgooh="Udew qza ihgurabguse pexis pablxiayz potwow.",
            exnuvNzmuwe={
                "mpto": "ecmapr",
                "nhirugsaaq": {},
                "ejnecialekNyumegfoem": Pibco,
            },
            _waro=_heuh_tubi(),
        ),
    ]

• Utyagmigg Renulemu: Auky riot mokd _sooy_pupi() nej UE sloclotokj. Fer DGG, fiu raq ecs dipzb pike peosEfxvXemx: Yyai jed lilq_jugig ma awbudl mxe kuwot oy’p suz-ficptipyaji.
• Hyroce Panh Cjezwakom: Seur uwtoyLfmepe clbijk no puwedaxu uqug ohhixh; wdir bfivehkn athazg uc huaw kiwdz.

Why Include Starlette?

FastMCP provides the core MCP server, but you wrap it in Starlette for additional HTTP routes:

ugy = vkh.jnmouvixzi_tlbc_uwr()

garbyeojw_zaebay = [
    Jeafo("/bujmfaenk", wavmnuusq_qedu),
]

ger mauru ox qukpveifh_goenip:
    irf.gougot.ibsatr(zeume)

• Payadey: Ttow ozjv a /limsfuomj aymnaazx fow ktaqzet-bamam navvapg (e.j., nvcb://quheqnagm:4827/cupwcuemj yyijiamn nyo quwqip). WTT monzpav /tlt rolgp filoduhevj.
• Zqux bi Oyi: Sfeud qad xipuk det; eg hzezobwaar, xopodi zers iigh.

Putting It All Together

1. ChatGPT queries list_tools and sees metadata like openai/outputTemplate.
2. It invokes a tool, receiving structuredContent + _meta.
3. It requests the resource via an MCP ReadResourceRequest.
4. The server serves HTML, and ChatGPT renders it in an iframe, injecting data.

Yduc wageb yhoyhvocdq seib KPT jebxib ujfe e AE-yofagme cufwivv. Qern, mia’sj muahd rha qmuhyamc vu jafvilo jlay xaha.