feat: add hiddenFromAgents/onlyReadsData agent flags, rename isDangerous

Author: NoOne7135

adminforth/documentation/docs/tutorial/09-Plugins/01-agent.md

@@ -668,28 +668,19 @@ To define a custom tool, register an API endpoint with `admin.express.endpoint`.
 
 By default, `admin.express.endpoint` applies AdminForth authorization. The endpoint handler receives `adminUser` from the user who is controlling the agent. In other words, all permissions and access rights of the agent are defined by that admin user. At the same time, actions done by the agent are automatically attributed in the audit log to the admin user who is controlling the agent.
 
-If a tool is risky, you can attach AdminForth agent metadata directly to the endpoint with the `agent` field.
+You can attach AdminForth agent metadata directly to the endpoint with the `agent` field.
 
 ```ts
-type AgentRiskLevel = 'safe' | 'danger';
-
 type AgentToolMeta = {
-  riskLevel?: AgentRiskLevel;
-  confirmation?: {
-    title?: string;
-    message?: string;
-    confirmLabel?: string;
-  };
+  requiresHumanApproval?: boolean;
+  hiddenFromAgents?: boolean;
+  onlyReadsData?: boolean;
 };
 ```
 
-Use it in `.endpoint(...)` like this:
-
-- `riskLevel: 'safe'` marks the tool as low-risk.
-- `riskLevel: 'danger'` marks the tool as dangerous.
-- `confirmation` customizes the confirmation dialog shown before the tool is executed.
-
-This metadata is rendered into the generated OpenAPI document, so the agent can understand that a tool is dangerous and requires an explicit confirmation UI before execution.
+- `requiresHumanApproval: true` makes the agent ask the user for approval before it runs the tool. MCP clients receive the `destructiveHint` annotation.
+- `hiddenFromAgents: true` keeps the endpoint out of agent tools, both in the agent and in the [MCP server](/docs/tutorial/Plugins/mcp/). Use it for endpoints that serve your admin panel UI and must not be called by agents.
+- `onlyReadsData: true` declares that the endpoint does not change any data. MCP clients receive the `readOnlyHint` annotation, and a [read-only MCP server](/docs/tutorial/Plugins/mcp/#read-only-mode) exposes only such endpoints.
 
 This example uses the same email adapter pattern shown in the Email Invite and Email Password Reset plugins. The transport below uses Mailgun only to keep the snippet short; you can replace it with SES or any other adapter from [List of adapters](/docs/tutorial/ListOfAdapters/).
 
@@ -728,12 +719,7 @@ export function initApi(app: Express, admin: IAdminForth) {
     path: '/send_email_to_user',
     description: 'Send an email to one AdminForth user by id. Use this after the user row is resolved.',
     agent: {
-      riskLevel: 'danger',
-      confirmation: {
-        title: 'Send email to user',
-        message: 'This action will send a real email to the selected user.',
-        confirmLabel: 'Send email',
-      },
+      requiresHumanApproval: true,
     },
     request_schema: {
       type: 'object',

adminforth/documentation/docs/tutorial/09-Plugins/30-mcp.md

@@ -8,6 +8,8 @@ slug: /tutorial/Plugins/mcp
 
 The MCP plugin exposes AdminForth API methods as remote MCP tools. Every request runs as the AdminForth user who created the auth secret, so the same resource permissions, validation, and hooks apply.
 
+Endpoints marked with `agent: { hiddenFromAgents: true }` are not exposed. AdminForth and its plugins mark the endpoints the admin panel uses internally, such as login, two-factor authentication, passkeys, and agent chat. Mark your own endpoints the same way to keep them away from agents.
+
 ## Installation
 
 ```bash
@@ -27,6 +29,7 @@ model mcp_auth_secrets {
   created_at         DateTime
   last_used_at       DateTime?
   last_used_by_agent String?
+  read_only          Boolean   @default(false)
 
   @@index([user_id])
 }
@@ -58,6 +61,7 @@ export default {
     { name: 'created_at', type: AdminForthDataTypes.DATETIME },
     { name: 'last_used_at', type: AdminForthDataTypes.DATETIME, required: false },
     { name: 'last_used_by_agent', type: AdminForthDataTypes.STRING, required: false },
+    { name: 'read_only', type: AdminForthDataTypes.BOOLEAN },
   ],
   options: {
     allowedActions: {
@@ -94,6 +98,7 @@ new AdminForth({
         createdAtField: 'created_at',
         lastUsedAtField: 'last_used_at',
         lastUsedByAgentField: 'last_used_by_agent',
+        readOnlyField: 'read_only',
       },
     }),
   ],
@@ -118,6 +123,21 @@ Authorization: Bearer afmcp_...
 
 `last_used_at` and `last_used_by_agent` are updated in the background without running resource hooks. Client identity comes from per-request `io.modelcontextprotocol/clientInfo` metadata in MCP `2026-07-28`, with legacy `initialize` and `User-Agent` fallbacks.
 
+## Read-only mode
+
+A read-only auth secret lets an agent only read data. Check **Read only** when you create the auth secret in **MCP Settings**. The mode is stored in `read_only` and cannot be changed later: create a new auth secret instead.
+
+To make every auth secret read-only, set `readOnly: true` in the plugin options. The **Read only** checkbox is then hidden, and new auth secrets are stored as read-only, so they stay read-only if you remove the option later:
+
+```ts
+new AdminForthMcpPlugin({
+  readOnly: true,
+  // ...
+}),
+```
+
+In read-only mode the server exposes only endpoints marked with `agent: { onlyReadsData: true }`, such as `get_resource`, `get_resource_data`, and `aggregate`. Creating, updating, and deleting records and running actions are not available. To make your own endpoint available in read-only mode, mark it with `onlyReadsData: true`.
+
 ## Audit attribution
 
 To show which agent acted on behalf of a user, add a nullable field to the audit log table:

adminforth/modules/restApi.ts

@@ -803,6 +803,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       noAuth: true,
       method: 'POST',
       path: '/login',
+      agent: {
+        hiddenFromAgents: true,
+      },
       handler: async ({ body, response, headers, query, cookies, requestUrl, tr }) => {
 
         const INVALID_MESSAGE = await tr('Invalid username or password', 'errors');
@@ -904,6 +907,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
     server.endpoint({
       method: 'POST',
       path: '/check_auth',
+      agent: {
+        hiddenFromAgents: true,
+      },
       handler: async ({ adminUser }) => {
         return { ok: true };
       },
@@ -913,6 +919,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
         noAuth: true,
         method: 'POST',
         path: '/logout',
+        agent: {
+          hiddenFromAgents: true,
+        },
         handler: async ({ body, headers, query, cookies, requestUrl, response, tr }) => {
           // endpoint is noAuth (expired session should be able to log out as well), so user is resolved here
           const jwt = this.adminforth.auth.getAuthCookie(cookies);
@@ -931,6 +940,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       noAuth: true,
       method: 'GET',
       path: '/get_login_form_config',
+      agent: {
+        hiddenFromAgents: true,
+      },
       handler: async ({ tr }) => {
         const loginPromptHTML = await getLoginPromptHTML(this.adminforth.config.auth.loginPromptHTML);
         return {
@@ -943,6 +955,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       noAuth: true,
       method: 'GET',
       path: '/get_config',
+      agent: {
+        hiddenFromAgents: true,
+      },
       handler: async ({ body, query, headers, cookies, requestUrl, tr, response }): Promise<GetConfigResponse>=> {
         let username = ''
         let userFullName = ''
@@ -1145,6 +1160,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       method: 'GET', 
       path: '/get_menu_badges',
       description: 'Computes the current menu badge values for the authenticated admin user. Static badges are returned directly, and dynamic badge callbacks are resolved for all configured menu items, including nested items.',
+      agent: {
+        onlyReadsData: true,
+      },
       response_schema: getMenuBadgesResponseSchema,
       handler: async ({ adminUser }) => {
         const badges = {};
@@ -1189,6 +1207,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       method: 'POST',
       path: '/get_resource',
       description: 'Returns the definition of a single resource. The response includes translated labels, column metadata, allowed actions, visible bulk actions, frontend action metadata, and resource options after permission checks and removal of backend-only internals.',
+      agent: {
+        onlyReadsData: true,
+      },
       request_schema: getResourceRequestSchema,
       response_schema: getResourceResponseSchema,
       handler: async ({ body, adminUser, tr }): Promise<{ resource?: AdminForthResourceFrontend, error?: string }> => {
@@ -1400,6 +1421,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       method: 'POST',
       path: '/get_resource_data',
       description: 'Loads resource rows for list, show, or edit views. The endpoint validates access, applies request hooks, filters, sorting, pagination, record labels, and row click URLs, then returns the final dataset with resource options.',
+      agent: {
+        onlyReadsData: true,
+      },
       request_schema: getResourceDataRequestSchema,
       response_schema: getResourceDataResponseSchema,
       handler: async ({ body, adminUser, headers, query, cookies, requestUrl, abortSignal }) => {
@@ -1855,6 +1879,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       method: 'POST',
       path: '/aggregate',
       description: 'Performs aggregation queries (sum, count, avg, min, max, median) on a resource, with optional grouping by field value or date truncation. Requires list and show access to the resource, and only accepts columns the user can read on the show view: backend-only columns and columns hidden from the show view are rejected.',
+      agent: {
+        onlyReadsData: true,
+      },
       request_schema: aggregateRequestSchema,
       response_schema: aggregateResponseSchema,
       handler: async ({ body, adminUser, headers }) => {
@@ -1996,6 +2023,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       method: 'POST',
       path: '/get_resource_foreign_data',
       description: 'Loads dropdown options for a foreign-key column. It resolves the referenced resource or polymorphic resources, applies optional search text, hook-injected filters, pagination, and per-record labels, then returns sanitized option items.',
+      agent: {
+        onlyReadsData: true,
+      },
       request_schema: getResourceForeignDataRequestSchema,
       response_schema: getResourceForeignDataResponseSchema,
       handler: async ({ body, adminUser, headers, query, cookies, requestUrl }) => {
@@ -2193,6 +2223,9 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       method: 'POST',
       path: '/get_min_max_for_columns',
       description: 'Returns min and max values for resource columns that explicitly opt in to min/max queries. This is used to build range-based filter controls without exposing columns that do not allow the query.',
+      agent: {
+        onlyReadsData: true,
+      },
       request_schema: getMinMaxForColumnsRequestSchema,
       response_schema: getMinMaxForColumnsResponseSchema,
       handler: async ({ body }) => {
@@ -2226,7 +2259,7 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
         path: '/create_record',
       description: 'Creates a new record in the specified resource. The endpoint validates create permissions, required fields, hidden or backend-only field rules, polymorphic foreign keys, and resource hooks before persisting and returning the created primary key.',
       agent: {
-        isDangerous: true,
+        requiresHumanApproval: true,
       },
       request_schema: createRecordRequestSchema,
       response_schema: createRecordResponseSchema,
@@ -2403,7 +2436,7 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       path: '/update_record',
       description: 'Updates an existing record by primary key. The endpoint validates edit permissions, current record existence, hidden, backend-only, and read-only field rules, polymorphic foreign keys, and resource hooks before saving changes.',
       agent: {
-        isDangerous: true,
+        requiresHumanApproval: true,
       },
       request_schema: updateRecordRequestSchema,
       response_schema: updateRecordResponseSchema,
@@ -2575,7 +2608,7 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       path: '/delete_record',
       description: 'Deletes an existing record by primary key. The endpoint validates delete permissions, loads the current record, executes configured cascade child deletion, and then removes the record.',
       agent: {
-        isDangerous: true,
+        requiresHumanApproval: true,
       },
       request_schema: deleteRecordRequestSchema,
       response_schema: deleteRecordResponseSchema,
@@ -2664,7 +2697,7 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       path: '/start_custom_action',
       description: 'Executes a custom resource action for a single record. The endpoint validates the resource, action existence, and action permissions, then either returns a redirect URL or executes the action handler and returns its result together with action context.',
       agent: {
-        isDangerous: true,
+        requiresHumanApproval: true,
       },
       request_schema: startCustomActionRequestSchema,
       response_schema: startCustomActionResponseSchema,
@@ -2723,7 +2756,7 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
       path: '/start_custom_bulk_action',
       description: 'Executes a custom resource action in bulk mode for multiple records. The endpoint validates the resource, action existence, bulk handler availability, and permissions, then runs the bulk handler and returns its result together with action context.',
       agent: {
-        isDangerous: true,
+        requiresHumanApproval: true,
       },
       request_schema: startCustomBulkActionRequestSchema,
       response_schema: startCustomBulkActionResponseSchema,

adminforth/types/Back.ts

@@ -64,7 +64,9 @@ export interface IAdminForthAuthenticatedEndpointHandlerInput extends IAdminFort
 }
 
 export type AgentToolMeta = {
-  isDangerous?: boolean;
+  requiresHumanApproval?: boolean;
+  hiddenFromAgents?: boolean;
+  onlyReadsData?: boolean;
 };
 
 export interface IAdminForthEndpointOptionsBase {

dev-demo/globalPlugins.ts

@@ -55,6 +55,7 @@ export const globalPlugins = [
       createdAtField: 'created_at',
       lastUsedAtField: 'last_used_at',
       lastUsedByAgentField: 'last_used_by_agent',
+      readOnlyField: 'read_only',
     },
   }),
   new AdminForthAgent({

dev-demo/migrations/prisma/sqlite/migrations/20261007120000_add_mcp_auth_secret_read_only/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "mcp_auth_secrets" ADD COLUMN "read_only" BOOLEAN NOT NULL DEFAULT false;

dev-demo/migrations/prisma/sqlite/schema.prisma

@@ -65,6 +65,7 @@ model mcp_auth_secrets {
   created_at         DateTime
   last_used_at       DateTime?
   last_used_by_agent String?
+  read_only          Boolean  @default(false)
 
   @@index([user_id])
 }

dev-demo/resources/mcpAuthSecrets.ts

@@ -14,6 +14,7 @@ export default {
     { name: 'created_at', type: AdminForthDataTypes.DATETIME },
     { name: 'last_used_at', type: AdminForthDataTypes.DATETIME, required: false },
     { name: 'last_used_by_agent', type: AdminForthDataTypes.STRING, required: false },
+    { name: 'read_only', type: AdminForthDataTypes.BOOLEAN },
   ],
   options: {
     allowedActions: {