@lowdefy/docs-content 6.1.0 → 7.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (285) hide show
  1. package/README.md +1 -0
  2. package/content/actions/downloadcsv.md +1 -1
  3. package/content/actions/emailotpsend.md +58 -0
  4. package/content/actions/emailotpverify.md +79 -0
  5. package/content/actions/getlocalstorage.md +43 -0
  6. package/content/actions/link.md +47 -1
  7. package/content/actions/login.md +25 -5
  8. package/content/actions/logout.md +7 -5
  9. package/content/actions/magiclinkverify.md +117 -0
  10. package/content/actions/pdfmake.md +2 -2
  11. package/content/actions/posthogalias.md +29 -0
  12. package/content/actions/posthogcapture.md +49 -0
  13. package/content/actions/posthogcapturepageleave.md +38 -0
  14. package/content/actions/posthogfeatureflag.md +50 -0
  15. package/content/actions/posthoggroup.md +37 -0
  16. package/content/actions/posthogidentify.md +54 -0
  17. package/content/actions/posthoginit.md +96 -0
  18. package/content/actions/posthogoptin.md +29 -0
  19. package/content/actions/posthogoptout.md +29 -0
  20. package/content/actions/posthogpageview.md +37 -0
  21. package/content/actions/posthogreloadfeatureflags.md +47 -0
  22. package/content/actions/posthogreset.md +28 -0
  23. package/content/actions/posthogsetpersonproperties.md +36 -0
  24. package/content/actions/removelocalstorage.md +28 -0
  25. package/content/actions/resetvalidation.md +5 -3
  26. package/content/actions/setdarkmode.md +3 -3
  27. package/content/actions/setglobal.md +2 -0
  28. package/content/actions/setlocale.md +1 -1
  29. package/content/actions/setlocalstorage.md +34 -0
  30. package/content/actions/setstate.md +2 -0
  31. package/content/actions/validate.md +7 -4
  32. package/content/adapter-reference/mongodbauthadapter.md +46 -0
  33. package/content/agents/agent-endpoint-tools.md +24 -0
  34. package/content/agents/agent-properties.md +13 -3
  35. package/content/agents/agent-server-hooks.md +1 -1
  36. package/content/agents/agentchat.md +43 -7
  37. package/content/agents/agentconversations.md +42 -8
  38. package/content/agents/agents-introduction.md +107 -0
  39. package/content/callback-reference/auth0logoutcallback.md +54 -0
  40. package/content/concepts/ai-agent-docs.md +455 -106
  41. package/content/concepts/blocks.md +150 -0
  42. package/content/concepts/connections-and-requests.md +402 -0
  43. package/content/concepts/custom-html.md +42 -0
  44. package/content/concepts/custom-styling.md +50 -5
  45. package/content/concepts/dynamic-page-content.md +309 -0
  46. package/content/concepts/events-and-actions.md +154 -2
  47. package/content/concepts/four-primitives.md +31 -0
  48. package/content/concepts/html-attributes.md +293 -0
  49. package/content/concepts/i18n.md +8 -3
  50. package/content/concepts/keyboard-shortcuts.md +2 -2
  51. package/content/concepts/layout-overview.md +1 -1
  52. package/content/concepts/logger.md +99 -0
  53. package/content/concepts/lowdefy-api.md +1319 -0
  54. package/content/concepts/lowdefy-schema.md +136 -3
  55. package/content/concepts/menus.md +8 -7
  56. package/content/concepts/module-authoring.md +76 -5
  57. package/content/concepts/modules.md +3 -1
  58. package/content/concepts/notifications.md +180 -0
  59. package/content/concepts/operators.md +7 -0
  60. package/content/concepts/page-and-app-state.md +252 -0
  61. package/content/concepts/page-paths.md +209 -0
  62. package/content/concepts/theming.md +582 -0
  63. package/content/connections/aigateway.md +375 -0
  64. package/content/connections/anthropic.md +169 -2
  65. package/content/connections/awss3.md +178 -2
  66. package/content/connections/axioshttp.md +181 -0
  67. package/content/connections/google.md +169 -2
  68. package/content/connections/mongodb.md +1014 -3
  69. package/content/connections/openai-connection.md +169 -2
  70. package/content/connections/sendgridmail.md +2 -0
  71. package/content/connections/smtp.md +3 -1
  72. package/content/connections/treg.md +329 -0
  73. package/content/container-blocks/affix.md +47 -7
  74. package/content/container-blocks/alert.md +76 -24
  75. package/content/container-blocks/badge.md +100 -24
  76. package/content/container-blocks/box.md +9 -9
  77. package/content/container-blocks/card.md +132 -27
  78. package/content/container-blocks/carousel.md +60 -7
  79. package/content/container-blocks/collapse.md +153 -9
  80. package/content/container-blocks/configprovider.md +35 -13
  81. package/content/container-blocks/confirmmodal.md +69 -23
  82. package/content/container-blocks/content.md +62 -98
  83. package/content/container-blocks/descriptions.md +45 -4
  84. package/content/container-blocks/drawer.md +139 -28
  85. package/content/container-blocks/dropdownmenu.md +119 -31
  86. package/content/container-blocks/flex.md +40 -62
  87. package/content/container-blocks/footer.md +15 -11
  88. package/content/container-blocks/googlemapsheatmap.md +1 -1
  89. package/content/container-blocks/googlemapsscript.md +2 -2
  90. package/content/container-blocks/header.md +71 -36
  91. package/content/container-blocks/label.md +34 -7
  92. package/content/container-blocks/layout.md +52 -34
  93. package/content/container-blocks/masonry.md +17 -71
  94. package/content/container-blocks/mobilemenu.md +131 -88
  95. package/content/container-blocks/modal.md +161 -26
  96. package/content/container-blocks/pageheadermenu.md +138 -31
  97. package/content/container-blocks/pagesidebarlayout.md +230 -27
  98. package/content/container-blocks/pagesidermenu.md +153 -43
  99. package/content/container-blocks/popover.md +34 -31
  100. package/content/container-blocks/result.md +32 -21
  101. package/content/container-blocks/sider.md +85 -122
  102. package/content/container-blocks/span.md +7 -7
  103. package/content/container-blocks/spinner.md +3 -3
  104. package/content/container-blocks/splitter.md +150 -68
  105. package/content/container-blocks/tabs.md +64 -12
  106. package/content/container-blocks/tooltip.md +22 -46
  107. package/content/container-blocks/watermark.md +22 -4
  108. package/content/controls/parallel_for.md +21 -2
  109. package/content/controls/reject.md +24 -3
  110. package/content/controls/return.md +17 -1
  111. package/content/controls/throw.md +1 -0
  112. package/content/controls/try.md +4 -2
  113. package/content/controls/while.md +46 -0
  114. package/content/deployment/deployment-environments.md +10 -7
  115. package/content/deployment/docker.md +22 -7
  116. package/content/deployment/node-server.md +4 -0
  117. package/content/deployment/vercel.md +17 -6
  118. package/content/display-blocks/aggrid.md +33 -16
  119. package/content/display-blocks/anchor.md +16 -15
  120. package/content/display-blocks/avatar.md +57 -37
  121. package/content/display-blocks/breadcrumb.md +70 -21
  122. package/content/display-blocks/button.md +93 -19
  123. package/content/display-blocks/calendar.md +12 -0
  124. package/content/display-blocks/clickablehtml.md +239 -0
  125. package/content/display-blocks/dangeroushtml.md +1 -1
  126. package/content/display-blocks/difflist.md +1 -1
  127. package/content/display-blocks/difftimeline.md +1 -1
  128. package/content/display-blocks/divider.md +64 -3
  129. package/content/display-blocks/dropdownbutton.md +81 -30
  130. package/content/display-blocks/echart.md +35 -1
  131. package/content/display-blocks/eventlog.md +363 -0
  132. package/content/display-blocks/floatbutton.md +129 -42
  133. package/content/display-blocks/html.md +61 -1
  134. package/content/display-blocks/icon.md +250 -67
  135. package/content/display-blocks/img.md +2 -2
  136. package/content/display-blocks/menu.md +146 -73
  137. package/content/display-blocks/message.md +38 -124
  138. package/content/display-blocks/notification.md +94 -222
  139. package/content/display-blocks/paragraph.md +59 -9
  140. package/content/display-blocks/pollingtimer.md +263 -0
  141. package/content/display-blocks/progress.md +96 -17
  142. package/content/display-blocks/qrcode.md +19 -4
  143. package/content/display-blocks/s3download.md +1 -1
  144. package/content/display-blocks/search.md +19 -9
  145. package/content/display-blocks/skeletonbutton.md +1 -0
  146. package/content/display-blocks/skeletoninput.md +1 -0
  147. package/content/display-blocks/statistic.md +75 -17
  148. package/content/display-blocks/steps.md +58 -25
  149. package/content/display-blocks/table.md +2527 -0
  150. package/content/display-blocks/tablelight.md +621 -0
  151. package/content/display-blocks/tag.md +102 -17
  152. package/content/display-blocks/title.md +50 -11
  153. package/content/display-blocks/tour.md +33 -23
  154. package/content/input-blocks/autocomplete.md +81 -9
  155. package/content/input-blocks/buttonselector.md +45 -8
  156. package/content/input-blocks/captcha.md +40 -0
  157. package/content/input-blocks/checkboxselector.md +97 -7
  158. package/content/input-blocks/checkboxswitch.md +33 -3
  159. package/content/input-blocks/colorselector.md +63 -14
  160. package/content/input-blocks/daterangeselector.md +165 -45
  161. package/content/input-blocks/dateselector.md +139 -41
  162. package/content/input-blocks/datetimeselector.md +158 -49
  163. package/content/input-blocks/inputgallery.md +3 -3
  164. package/content/input-blocks/intentinput.md +207 -0
  165. package/content/input-blocks/monthselector.md +120 -52
  166. package/content/input-blocks/multipleselector.md +150 -39
  167. package/content/input-blocks/numberinput.md +98 -12
  168. package/content/input-blocks/pagination.md +70 -14
  169. package/content/input-blocks/paragraphinput.md +51 -37
  170. package/content/input-blocks/passwordinput.md +60 -6
  171. package/content/input-blocks/phonenumberinput.md +59 -26
  172. package/content/input-blocks/placesautocomplete.md +319 -0
  173. package/content/input-blocks/radioselector.md +83 -7
  174. package/content/input-blocks/ratingslider.md +57 -26
  175. package/content/input-blocks/s3uploadbutton.md +24 -24
  176. package/content/input-blocks/s3uploaddragger.md +3 -3
  177. package/content/input-blocks/s3uploadphoto.md +5 -5
  178. package/content/input-blocks/segmentedselector.md +72 -32
  179. package/content/input-blocks/selector.md +109 -21
  180. package/content/input-blocks/switch.md +65 -17
  181. package/content/input-blocks/tableinput.md +445 -0
  182. package/content/input-blocks/tagmultipleselector.md +114 -0
  183. package/content/input-blocks/tagselector.md +114 -0
  184. package/content/input-blocks/textarea.md +32 -3
  185. package/content/input-blocks/textinput.md +70 -29
  186. package/content/input-blocks/tiptapinput.md +1 -1
  187. package/content/input-blocks/tiptapmentioninput.md +2 -2
  188. package/content/input-blocks/titleinput.md +39 -12
  189. package/content/input-blocks/treeinput.md +49 -25
  190. package/content/input-blocks/treemultipleselector.md +127 -10
  191. package/content/input-blocks/treeselector.md +97 -9
  192. package/content/input-blocks/upload.md +64 -15
  193. package/content/input-blocks/uploaddragger.md +17 -1
  194. package/content/input-blocks/uploadphoto.md +18 -1
  195. package/content/input-blocks/weekselector.md +120 -55
  196. package/content/learn/introduction.md +27 -0
  197. package/content/learn/quickstart.md +53 -0
  198. package/content/learn/showcase.md +8 -0
  199. package/content/list-blocks/controlledlist.md +24 -15
  200. package/content/list-blocks/list.md +11 -11
  201. package/content/list-blocks/masonrylist.md +7 -34
  202. package/content/migration/auth-upgrade.md +337 -0
  203. package/content/migration/upgrade-guide.md +1 -0
  204. package/content/migration/v3-to-v4.md +417 -0
  205. package/content/migration/v6-to-v7.md +620 -0
  206. package/content/operators/_agent.md +155 -0
  207. package/content/operators/_app.md +2 -1
  208. package/content/operators/_array.md +122 -1
  209. package/content/operators/_build.md +1 -0
  210. package/content/operators/_credential.md +57 -0
  211. package/content/operators/_cron.md +292 -0
  212. package/content/operators/_date.md +2 -0
  213. package/content/operators/_error.md +24 -1
  214. package/content/operators/_get.md +6 -6
  215. package/content/operators/_hmac.md +78 -0
  216. package/content/operators/_js.md +2 -1
  217. package/content/operators/_location.md +1 -1
  218. package/content/operators/_media.md +13 -0
  219. package/content/operators/_module.md +56 -2
  220. package/content/operators/_operator.md +17 -3
  221. package/content/operators/_path_params.md +82 -0
  222. package/content/operators/_ref.md +258 -0
  223. package/content/operators/_request.md +1 -1
  224. package/content/operators/_request_details.md +6 -0
  225. package/content/operators/_type.md +14 -3
  226. package/content/operators/_url_query.md +2 -0
  227. package/content/operators/_user.md +3 -3
  228. package/content/plugins/plugins-actions.md +10 -0
  229. package/content/plugins/plugins-connections.md +25 -0
  230. package/content/plugins/plugins-dev.md +66 -0
  231. package/content/plugins/plugins-icon-sets.md +267 -0
  232. package/content/plugins/plugins-introduction.md +27 -1
  233. package/content/plugins/plugins.md +19 -0
  234. package/content/plugins/posthog.md +359 -0
  235. package/content/provider-reference/auth-js-providers.md +107 -0
  236. package/content/provider-reference/openidconnectprovider.md +44 -0
  237. package/content/recipes/recipes.md +16 -0
  238. package/content/reference/actions-reference.md +31 -0
  239. package/content/reference/blocks-reference.md +35 -0
  240. package/content/reference/cli.md +403 -0
  241. package/content/reference/connections-reference.md +23 -0
  242. package/content/reference/operators-reference.md +47 -0
  243. package/content/reference/reference.md +16 -0
  244. package/content/reference/schema-reference.md +12 -0
  245. package/content/testing/config-tests.md +677 -0
  246. package/content/testing/e2e-configuration.md +31 -1
  247. package/content/testing/e2e-getting-started.md +1 -1
  248. package/content/testing/e2e-introduction.md +1 -1
  249. package/content/testing/e2e-writing-tests.md +12 -1
  250. package/content/testing/explore-pull-request.md +136 -0
  251. package/content/testing/journey-data-sets.md +326 -0
  252. package/content/tutorial/tutorial-actions-operators.md +2 -2
  253. package/content/tutorial/tutorial-add-blocks.md +2 -2
  254. package/content/tutorial/tutorial-create-page.md +48 -2
  255. package/content/tutorial/tutorial-display-data-page.md +3 -3
  256. package/content/tutorial/tutorial-requests-api.md +155 -0
  257. package/content/tutorial/tutorial-requests-sql.md +153 -0
  258. package/content/tutorial/tutorial-start.md +66 -1
  259. package/content/user-authentication/auth-configuration.md +267 -0
  260. package/content/user-authentication/auth-providers.md +24 -0
  261. package/content/user-authentication/auth-steps.md +141 -0
  262. package/content/user-authentication/login-and-logout.md +160 -8
  263. package/content/user-authentication/mcp-oauth.md +424 -0
  264. package/content/user-authentication/organizations.md +246 -0
  265. package/content/user-authentication/protected-pages-apis.md +97 -0
  266. package/content/user-authentication/roles.md +49 -0
  267. package/content/user-authentication/two-factor.md +229 -0
  268. package/content/user-authentication/user-object.md +58 -0
  269. package/content/user-authentication/users-introduction.md +8 -0
  270. package/content/websockets/websocket-publish.md +105 -0
  271. package/content/websockets/websocket-subscriptions.md +136 -0
  272. package/content/websockets/websockets-introduction.md +101 -0
  273. package/hazards.json +56 -0
  274. package/index.json +3458 -14
  275. package/package.json +10 -1
  276. package/scripts/extractAgentDocs.js +41 -30
  277. package/scripts/hashDocSources.js +38 -0
  278. package/scripts/isRedirectPage.js +26 -0
  279. package/scripts/recordSourceHashes.js +97 -0
  280. package/scripts/resolvePageSections.js +42 -0
  281. package/scripts/sectionKind.js +27 -0
  282. package/content/concepts/cli.md +0 -223
  283. package/content/other/introduction.md +0 -39
  284. package/content/other/next-auth-providers.md +0 -3
  285. /package/content/{other → actions}/updatesession.md +0 -0
@@ -0,0 +1,424 @@
1
+ # MCP Server & OAuth
2
+
3
+ A Lowdefy app can expose its API endpoints as tools to an MCP client — Claude, ChatGPT, an IDE assistant — over the Model Context Protocol. When those tools touch anything but public data, the client has to prove who is calling, and Lowdefy handles that by turning the app itself into an **OAuth 2.1 authorization server**: the assistant runs a normal browser authorization, the user signs in, chooses the organization to work in, and grants consent, and the app mints an access token the assistant sends on every tool call.
4
+
5
+ This page is about the *authenticated* MCP surface. Exposing tools to an app's own agents, and the `mcp` array on an agent (the app acting as an MCP *client*), are covered in [MCP tools for agents](/agent-mcp-tools) and the [`Mcp` connection](/Mcp). Here the app is the *server*, and the caller is an outside assistant.
6
+
7
+ ## One resource, one address
8
+
9
+ There is a single MCP resource for the whole deployment, served at `/api/mcp`. The organization a call acts in is **not** part of the address — it is chosen once during authorization and carried inside the access token as a claim. Every assistant connects to the same URL; two users, or one user in two organizations, are told apart by their tokens, never by the path.
10
+
11
+ This is the Linear model — one link, the workspace is a property of the authorization rather than the address — and it is deliberate. An earlier design keyed the resource per organization (`/api/mcp/{organization_id}`); that put the organization in the URL, the RFC 8707 `resource` parameter, and the token audience, and needed a per-organization resource row kept in sync. The single resource deletes all of that: one address to paste, one audience, and the organization rides the token.
12
+
13
+ | Route | Purpose |
14
+ | ----- | ------- |
15
+ | `POST /api/mcp` | The MCP resource — streamable HTTP transport. Tools are listed and called here, per request, authorized against the bearer token. |
16
+ | `GET /.well-known/oauth-protected-resource/api/mcp` | RFC 9728 protected-resource metadata: the resource URI, the authorization server, and the scopes it supports. Public and constant per deployment. |
17
+ | `GET /.well-known/oauth-authorization-server/api/auth` | RFC 8414 authorization-server metadata, re-exposed at the path a client derives from the issuer. |
18
+ | `/api/auth/*` | The authorization server itself — authorize, token, registration, and the OAuth endpoints the consent and picker pages call. |
19
+
20
+ The `/.well-known` documents derive their URIs from the pinned canonical URL (`BETTER_AUTH_URL`, else the current environment's `url`), never from a request `Host` header, so they are the same for every caller. They mount **only when `auth.oauthProvider` is configured** — an app that is not an authorization server has nothing to discover, and its MCP tools are all public (see the rule below).
21
+
22
+ ## Turning the app into an authorization server
23
+
24
+ Add `auth.oauthProvider`. It names the two pages the browser authorization flow hands control to, and whether unknown clients may register themselves:
25
+
26
+ ```yaml
27
+ auth:
28
+ oauthProvider:
29
+ consentPage: /oauth-consent
30
+ postLoginPage: /oauth-select-organization
31
+ dynamicClientRegistration: false
32
+ ```
33
+
34
+ - **`consentPage`** *(required)* — the Lowdefy page id of your consent screen. The authorization flow redirects the signed-in user here to approve or deny the client. The engine builds the redirect as `${origin}${basePath}${consentPage}`, joined with no separator, so **the leading slash is required**.
35
+ - **`postLoginPage`** — the page where a signed-in user chooses which organization the authorization acts in. It is shown after login and before consent. It is **required under `organizations.policy: tenant`** (the build fails without it) and is skipped under `pinned`, where there is only ever one organization to act in.
36
+ - **`dynamicClientRegistration`** — allow unregistered MCP clients to self-register per RFC 7591. Off by default; pre-registered clients are the primary path. Turn it on for public assistants you cannot pre-register.
37
+
38
+ Both page ids are validated at build time the same way: the page must exist, and it must not be public-listed in a way that would let it render without a session — the flow only ever reaches them for a signed-in user.
39
+
40
+ ## Exposing tools, and their scopes
41
+
42
+ The app-level `mcp` block declares the server's identity and which API endpoints are tools:
43
+
44
+ ```yaml
45
+ mcp:
46
+ name: acme
47
+ version: '1.0.0'
48
+ title: Acme
49
+ websiteUrl: https://acme.example.com
50
+ instructions: Search for a customer before creating an invoice for them.
51
+ icons:
52
+ - src: https://acme.example.com/icon-512.png
53
+ mimeType: image/png
54
+ sizes: ['512x512']
55
+ endpoints:
56
+ - id: search-customers
57
+ scope: mcp:read
58
+ annotations:
59
+ title: Search customers
60
+ readOnlyHint: true
61
+ - id: create-invoice
62
+ scope: mcp:write
63
+ annotations:
64
+ title: Create invoice
65
+ destructiveHint: false
66
+ ```
67
+
68
+ `name`, `version`, `title`, `websiteUrl` and `icons` are the server branding a client shows the user in the `initialize` handshake. Each `endpoints` entry needs an `id` and a `scope`.
69
+
70
+ `annotations` is optional and sent with the tool in `tools/list`. `title` is the name a client shows for the tool. The hints tell a client how the tool behaves, and clients use them to decide whether to ask the user before calling it: `readOnlyHint` (the tool changes nothing), `destructiveHint` (a write may delete or overwrite data), `idempotentHint` (calling it twice with the same input has no further effect) and `openWorldHint` (it reaches systems outside the app). They are hints, not enforcement, and they are not derived from `scope`: an `mcp:read` tool can still write, so only set `readOnlyHint: true` on a tool that really changes nothing.
71
+
72
+ `instructions` is an optional string sent in the `initialize` result. Clients such as Claude Code place it in the model's system prompt, so use it for a short note on how the tools fit together or when to reach for them. Clients may truncate long instructions, so keep it to a few lines. When it is not set, the server sends no instructions.
73
+
74
+ **`scope` is a closed vocabulary — `mcp:read` or `mcp:write`, and nothing else.** Apps cannot mint their own scopes. `mcp:write` implies `mcp:read` at runtime, so a token granted write can call both. Tag a tool that only reads with `mcp:read` and one that mutates with `mcp:write`; the consent screen then lets a user grant an assistant read-only access to the whole surface if they choose.
75
+
76
+ Three rules the build enforces on every tool:
77
+
78
+ - **Only `Api` endpoints can be tools.** An `InternalApi` endpoint is not reachable as one — it has no external caller by design.
79
+ - **Every tool needs a `description` and a `payloadSchema`.** The description is what the assistant reads to decide when to call the tool; the `payloadSchema` becomes the tool's input schema. A tool with neither is not a usable tool, so the build refuses it.
80
+ - **The `mcp.agents` key is gone.** MCP agent tools are not supported; remove it if you are upgrading.
81
+
82
+ ## Running an endpoint after every tool call
83
+
84
+ `afterToolCall` names an API endpoint the server runs after each tool call, once the reply to the client is built. Use it to see what agents do with your tools: which tools they call, with what arguments, and what came back, refusals included.
85
+
86
+ ```yaml
87
+ mcp:
88
+ afterToolCall: record-tool-call
89
+ endpoints:
90
+ - id: search-customers
91
+ scope: mcp:read
92
+ ```
93
+
94
+ The endpoint is called with this payload:
95
+
96
+ | Field | Value |
97
+ | ----- | ----- |
98
+ | `tool` | The tool name the client called. |
99
+ | `endpoint_id` | The `id` of the tool's `mcp.endpoints` entry. |
100
+ | `scope` | The `scope` of that entry. |
101
+ | `payload` | The arguments the tool was called with. |
102
+ | `success` | `true` when the tool's endpoint succeeded, `false` when its routine errored or rejected. |
103
+ | `response` | The tool endpoint's response, or `null` when `success` is `false`. |
104
+
105
+ - **It cannot change the reply.** A hook endpoint that throws, is refused, or ends in an error or reject is logged as a warning naming the hook and the tool, and the client gets its reply as if there were no hook.
106
+ - **It runs as the tool's caller.** The hook sees the same user, so `_user` is the person the agent acts for, and the hook endpoint's auth is checked against that caller like a `CallApi` step. Give it auth every tool caller passes, or calls by the others are logged as refused.
107
+ - **It runs only for a call that reached its tool's endpoint.** An unknown or hidden tool, a role or scope shortfall and a payload the tool's `payloadSchema` rejects never reach the endpoint's routine, so they never run the hook.
108
+ - **The reply waits for it.** The hook finishes before the request does, so it is not cut short on serverless platforms that stop work once the response is sent. Keep it quick.
109
+
110
+ The hook is normally an `InternalApi` endpoint and is not listed in `mcp.endpoints`, so it is never offered as a tool. The build checks that the endpoint it names exists.
111
+
112
+ ## A tool is gated twice
113
+
114
+ When a call arrives at `/api/mcp`, a tool is listed and callable only when **both** hold:
115
+
116
+ 1. the caller's **role outcome** allows the endpoint — the same `auth.api` / `auth.api.roles` gate every API call passes; and
117
+ 2. the **token's granted scope** covers the tool's tag.
118
+
119
+ The 401 challenge is decided once, at the route boundary, before the MCP transport runs. Past that boundary the transport answers over HTTP 200, so a role or scope shortfall never surfaces as a `403` or an `insufficient_scope` error to the assistant — the tool is simply not offered. This is intentional: the tool surface does not disclose the existence of tools the caller may not use.
120
+
121
+ ## The rule that catches everyone: keep MCP endpoints out of `auth.api.public`
122
+
123
+ > **Never list an MCP endpoint id in `auth.api.public`.**
124
+
125
+ One public tool suppresses the 401 challenge for the *whole* route. The build sets `mcp.json`'s `hasPublicTool` flag when any exposed endpoint is public, and the `/api/mcp` route then serves an anonymous caller a `200` with the public tools instead of a `401` with the `WWW-Authenticate` challenge. A freshly added assistant reports "connected, 1 tool" and **never runs the OAuth flow** — only a *stale* token would take the challenge branch. Every protected tool then sits behind a door the client was never told to knock on.
126
+
127
+ So a protected app keeps its `auth.api` gates and leaves every `mcp.endpoints` id out of the public list:
128
+
129
+ ```yaml
130
+ auth:
131
+ api:
132
+ protected: true
133
+ # Keep MCP endpoint ids OUT of this list. A single public tool
134
+ # flips mcp.json hasPublicTool, and /api/mcp then serves anonymous
135
+ # callers a 200 with that tool instead of the 401 challenge.
136
+ public:
137
+ - webhooks/stripe # a webhook receiver, not an MCP tool
138
+ ```
139
+
140
+ The build has a matching guard from the other direction: a protected or role-gated MCP endpoint **requires** `auth.oauthProvider`. Without the authorization server there is no way to authenticate the caller, so the build fails rather than shipping an unreachable tool — make the endpoint public (accepting the trade above) or configure `oauthProvider`.
141
+
142
+ ## The authorization flow, end to end
143
+
144
+ 1. The assistant reads `/.well-known/oauth-protected-resource/api/mcp`, finds the authorization server, and (if it is not pre-registered and `dynamicClientRegistration` is on) registers itself.
145
+ 2. It opens a browser to the authorization endpoint. The user signs in through your normal sign-in page.
146
+ 3. **Under `tenant`,** the flow redirects to `postLoginPage`. The user picks the organization to work in; the page sets it active and continues the authorization. **Under `pinned`,** this step is skipped.
147
+ 4. The flow redirects to `consentPage`. The user approves the client and the requested scopes — or, if they have already consented for this client in this organization, consent is skipped.
148
+ 5. The app mints an access token whose **`organization_id` claim is the chosen organization** (the consent `referenceId`), and the assistant sends it as a `Bearer` token on every `/api/mcp` call.
149
+
150
+ Consent is recorded per **(client, user, organization)**. Re-authorizing into an organization the user has already consented for skips the consent screen; a first authorization into a *different* organization asks for consent again, for that organization.
151
+
152
+ ### How a token becomes a caller
153
+
154
+ On every `/api/mcp` request the token is verified in-process against the authorization server's own signing keys: the issuer and audience must match the resource, and the token must carry both a `sub` (the user) and an `organization_id` claim. The claim is not trusted on its own — the **consent row for `(client, user, organization)` must still exist**. That liveness read on every call is what makes switching and disconnecting take effect *immediately*: revoke the grant and the next call is refused at once, not at the token's expiry.
155
+
156
+ The caller is then resolved as a member of that organization, exactly as a session caller is — same membership wall, same role source, same `_user` shape — with one extra field: **`_user.auth_method` is `'mcp'`**, so a routine can tell an assistant apart from a browser without any app-side plumbing.
157
+
158
+ ```yaml
159
+ # In an endpoint routine, branch on how the caller arrived:
160
+ - id: set_channel
161
+ type: SetState
162
+ params:
163
+ channel:
164
+ _if:
165
+ test:
166
+ _eq:
167
+ - _user: auth_method
168
+ - mcp
169
+ then: mcp
170
+ else: ui
171
+ ```
172
+
173
+ A token that cannot be verified (for example, an opaque token minted because the client omitted the RFC 8707 `resource` parameter), one whose grant has been revoked, or one whose user is no longer a member of the token's organization (removed, left, or the user deleted), gets a `401` with a `WWW-Authenticate` challenge that tells the client what to do — reconnect and re-run the authorization, including the organization choice. The authorization server also refuses to refresh a grant whose user is no longer a member of its organization (`invalid_grant`), so a client holding a refresh token falls back to the full authorization instead of refreshing into another refused token.
174
+
175
+ ## Building the consent and picker pages
176
+
177
+ Both pages are ordinary Lowdefy pages that read the authorization request from the URL query, show the user what is being asked, and finish the flow with client actions. Four actions do the work:
178
+
179
+ | Action | What it does |
180
+ | ------ | ------------ |
181
+ | `ListOrganizations` | Returns the caller's organization memberships — the rows the picker renders. |
182
+ | `SetActiveOrganization` | Sets the caller's active organization. The picker calls it for the chosen organization. |
183
+ | `OAuthContinue` | Continues the authorization after the organization is chosen (`POST /api/auth/oauth2/continue`). Returns `{ url }` to redirect to. |
184
+ | `OAuthConsent` | Approves (`accept: true`) or denies (`accept: false`) the client. Returns `{ url }` to redirect to. |
185
+
186
+ ### The organization picker (`postLoginPage`)
187
+
188
+ On mount the page calls `ListOrganizations` and stores the rows in state; a `ListSelector` renders them, and its click handler sets the chosen organization active and continues:
189
+
190
+ ```yaml
191
+ id: select_org_rows
192
+ type: ListSelector
193
+ properties:
194
+ selectable: false
195
+ hoverable: true
196
+ data:
197
+ _state: organizations
198
+ events:
199
+ onClick:
200
+ - id: set_active_organization
201
+ type: SetActiveOrganization
202
+ skip:
203
+ _eq:
204
+ - _event: item.id
205
+ - _user: organization_id
206
+ params:
207
+ organizationId:
208
+ _event: item.id
209
+ - id: continue_authorization
210
+ type: OAuthContinue
211
+ messages:
212
+ error: false
213
+ - id: continue_redirect
214
+ type: Link
215
+ params:
216
+ url:
217
+ _actions: continue_authorization.response.url
218
+ ```
219
+
220
+ `SetActiveOrganization` is skipped when the chosen organization is already the active one, so re-picking the current organization is a no-op that still continues the flow.
221
+
222
+ ### The consent screen (`consentPage`)
223
+
224
+ Reads the request from the query, shows the client and scopes, and finishes on the user's decision:
225
+
226
+ ```yaml
227
+ id: consent_allow
228
+ type: Button
229
+ properties:
230
+ title: Allow access
231
+ events:
232
+ onClick:
233
+ - id: consent_allow_action
234
+ type: OAuthConsent
235
+ messages:
236
+ error: false
237
+ params:
238
+ accept: true
239
+ - id: consent_allow_redirect
240
+ type: Link
241
+ params:
242
+ url:
243
+ _actions: consent_allow_action.response.url
244
+ ```
245
+
246
+ The deny button is identical with `params: { accept: false }`. Read `_url_query: client_id` and `_url_query: scope` to render what the client is asking for, and `_url_query: resource` to confirm the audience. Fetch the client's own metadata (name, logo) from `/api/auth/oauth2/public-client?client_id=...` to show a human-readable client name rather than an opaque id.
247
+
248
+ ## Switching organization from the assistant
249
+
250
+ An assistant connected to one organization switches by *disconnecting* — the client then re-runs the authorization and the user picks a different organization. Expose a tool that revokes the calling grant with the `RevokeMcpGrant` step:
251
+
252
+ ```yaml
253
+ id: switch-organization
254
+ type: Api
255
+ description: >
256
+ Disconnect this assistant from the organization it is connected to so
257
+ the user can connect it to another one. Use ONLY when the user asks to
258
+ work in a different organization. After it succeeds the connection is
259
+ gone: tell the user to reconnect in their assistant — the browser will
260
+ ask which organization to connect to.
261
+ payloadSchema:
262
+ type: object
263
+ additionalProperties: false
264
+ properties: {}
265
+ routine:
266
+ - id: revoke_grant
267
+ type: RevokeMcpGrant
268
+ - ':return':
269
+ disconnected: true
270
+ organization_id:
271
+ _step: revoke_grant.organizationId
272
+ message: >-
273
+ Disconnected. Ask the user to reconnect in their assistant.
274
+ ```
275
+
276
+ [`RevokeMcpGrant`](/auth-steps) reads the calling token's `(client, user, organization)` from the request context, deletes that one consent row, and deletes its access and refresh tokens. It is **caller-scoped**: it touches only the grant the call arrived on, so another assistant the same person connected, or this assistant's grant in another organization, is untouched. It refuses to run for any caller that did not arrive over MCP — there is no grant behind a browser session for it to revoke.
277
+
278
+ Expose it as an `mcp:read` tool. The next tool call the assistant makes gets a `401`, the client re-runs OAuth, and the user lands back on the organization picker.
279
+
280
+ ## Disconnecting assistants from the app
281
+
282
+ The mirror control belongs in your app's UI: a person removing every assistant connected to their active organization. It deletes the caller's consent rows, access tokens and refresh tokens for that organization — what `RevokeMcpGrant` does, scoped to the active organization instead of one client. Delete the access tokens before the refresh tokens they reference, and delete the refresh tokens rather than marking them revoked: the authorization server treats a revoked refresh token presented again as theft, and the client's next refresh would then delete every token it holds for the user, in every organization:
283
+
284
+ ```yaml
285
+ id: disconnect-assistants
286
+ type: Api
287
+ description: Disconnect every assistant connected to the caller's active organization.
288
+ payloadSchema:
289
+ type: object
290
+ additionalProperties: false
291
+ properties: {}
292
+ routine:
293
+ - id: delete_access_tokens
294
+ type: MongoDBDeleteMany
295
+ connectionId: oauth-access-tokens
296
+ properties:
297
+ filter:
298
+ user_id:
299
+ _user: id
300
+ reference_id:
301
+ _user: organization_id
302
+ - id: delete_refresh_tokens
303
+ type: MongoDBDeleteMany
304
+ connectionId: oauth-refresh-tokens
305
+ properties:
306
+ filter:
307
+ user_id:
308
+ _user: id
309
+ reference_id:
310
+ _user: organization_id
311
+ - id: delete_consents
312
+ type: MongoDBDeleteMany
313
+ connectionId: oauth-consents
314
+ properties:
315
+ filter:
316
+ user_id:
317
+ _user: id
318
+ reference_id:
319
+ _user: organization_id
320
+ - ':return':
321
+ disconnected:
322
+ _step: delete_consents.deletedCount
323
+ ```
324
+
325
+ Because the `/api/mcp` route reads the live consent row on every call, every affected assistant is refused on its next call, not at token expiry.
326
+
327
+ ## Tokens for scripts
328
+
329
+ An assistant a person connects from a browser holds an OAuth grant. A script that runs on its own — a worker loop, a CI job — has no browser to sign in again when something goes wrong, so it uses a **member token** instead: a long-lived bearer a member creates for themselves, stored hashed, that the script sends on every call to `/api/mcp`.
330
+
331
+ A member token needs the authorization server above (`auth.oauthProvider`). Without it the route authenticates nobody, so a token would reach nothing, and `CreateMcpToken` refuses.
332
+
333
+ A call with a member token is served as the member who made it: their roles, attributes and organization, read live on every call, and `_user.auth_method` is `'mcp'`, the same as an assistant. A token carries both `mcp:read` and `mcp:write`, so the member's roles alone decide which tools it reaches.
334
+
335
+ ### Creating a token
336
+
337
+ A member creates a token for themselves, in their active organization, from a signed-in session. `CreateMcpToken` refuses any other caller — an assistant, another token, an API strategy caller — so nothing that holds a narrower or shorter-lived credential can turn it into a token.
338
+
339
+ ```yaml
340
+ id: create-mcp-token
341
+ type: Api
342
+ payloadSchema:
343
+ type: object
344
+ additionalProperties: false
345
+ required: [name, expires_in_days]
346
+ properties:
347
+ name:
348
+ type: string
349
+ minLength: 1
350
+ expires_in_days:
351
+ type: [integer, 'null']
352
+ minimum: 1
353
+ routine:
354
+ - id: create
355
+ type: CreateMcpToken
356
+ properties:
357
+ name:
358
+ _payload: name
359
+ expiresInDays:
360
+ _payload: expires_in_days
361
+ - ':return':
362
+ _step: create
363
+ ```
364
+
365
+ `expiresInDays` is a positive whole number of days, or `null` for a token that never expires. The step sets no ceiling: an app that wants one checks the payload before the step. It returns `{ id, token, start, expiresAt }`. `token` appears here and nowhere else — only its SHA-256 and `start`, its first 12 characters, are stored — so show it once and tell the person to copy it.
366
+
367
+ A token starts with `ldf_mcp_`, so secret scanners and people can recognise a leaked one.
368
+
369
+ ### Calling with a token
370
+
371
+ The script sends the token as a bearer:
372
+
373
+ ```bash
374
+ curl https://app.example.com/api/mcp \
375
+ -H "Authorization: Bearer ldf_mcp_..." \
376
+ -H "Content-Type: application/json" \
377
+ -H "Accept: application/json, text/event-stream" \
378
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
379
+ ```
380
+
381
+ A refused token gets a `401` whose challenge says why, with no `resource_metadata`, since a script cannot sign in:
382
+
383
+ ```
384
+ WWW-Authenticate: Bearer error="invalid_token", error_description="This token has expired."
385
+ ```
386
+
387
+ The three reasons are *This token was switched off or does not exist*, *This token has expired*, and *This token's member can no longer use it*. The last covers a member who left or was removed, a deleted or banned user, and a token for an organization other than a pinned app's own. A token works only for the member row it was made for, so a member who leaves and rejoins holds none of their old tokens.
388
+
389
+ ### Switching a token off
390
+
391
+ `RevokeMcpToken` deletes one of the caller's own tokens by `id`. `RevokeOrgMcpToken` deletes any token in the organization, for owners and admins (`member: [update]`). Both return the token's `{ id, userId, memberId, name, start }` for an audit event, and the token is refused on its next call. `RemoveMember`, `LeaveOrganization` and `DeleteUser` delete the member's tokens too.
392
+
393
+ ### Listing tokens
394
+
395
+ Tokens live in the `user-mcp-tokens` collection, one document per token with `_id`, `organization_id`, `user_id`, `member_id`, `name`, `hash`, `start`, `created_at`, `expires_at` and `last_used_at` (written at most once an hour). Read them through a MongoDB connection, as the [disconnect example](#disconnecting-assistants-from-the-app) reads the OAuth collections, and always project out `hash`:
396
+
397
+ ```yaml
398
+ id: get_my_mcp_tokens
399
+ type: MongoDBFind
400
+ connectionId: mcp-tokens
401
+ properties:
402
+ query:
403
+ user_id:
404
+ _user: id
405
+ organization_id:
406
+ _user: organization_id
407
+ options:
408
+ projection:
409
+ hash: 0
410
+ sort:
411
+ created_at: -1
412
+ ```
413
+
414
+ For an owner's or admin's list, filter on `organization_id` alone. Pass a document's `_id` as `id` to the revoke steps.
415
+
416
+ ## Summary
417
+
418
+ - The app is an OAuth 2.1 authorization server; enable it with `auth.oauthProvider`.
419
+ - There is one MCP resource at `/api/mcp`. The organization is a token claim, not a URL segment.
420
+ - Tag each tool `mcp:read` or `mcp:write`; a tool is gated by both role and scope.
421
+ - **Never list an MCP endpoint id in `auth.api.public`** — one public tool suppresses the challenge for the whole route.
422
+ - Consent is per `(client, user, organization)` and read live on every call, so `RevokeMcpGrant` and disconnecting take effect immediately.
423
+ - `_user.auth_method` is `'mcp'` for assistant callers.
424
+ - A script uses a member token (`CreateMcpToken`), served as its member and switched off with `RevokeMcpToken` or `RevokeOrgMcpToken`.