Application Actions

Application actions are selected plugin backend methods that Senler adds to the installed project's MCP. They let AI work with application data or prepare settings for its tool or step at the user's request. Users do not add these methods to an agent or workflow manually: they appear only in projects where the plugin is installed and active.

This is a separate plugin capability:

• an agent tool is called by the agent during a conversation;
• an application step runs inside an automation process;
• an application action is called by AI through MCP while it helps with the plugin's interface and settings.

Prepare The Backend And OpenAPI

Publish OpenAPI 3 JSON at an address that Senler servers can reach. Production requires a public HTTPS URL. Senler does not follow redirects, waits up to 5 seconds for the schema, and accepts a document up to 5 MB. The loaded schema is cached for about 30 seconds, so a change may not appear in the catalog immediately.

You can mark GET, POST, PUT, PATCH, and DELETE operations. Describe path and query parameters as regular OpenAPI parameters and the body as an application/json object. Do not add project_id to action parameters: Senler already knows the project from the verified MCP context.

Add the x-senler-app-action extension to every permitted operation:

{
  "paths": {
    "/api/orders": {
      "get": {
        "summary": "List orders",
        "x-senler-app-action": {
          "version": 1,
          "name": "list_orders",
          "context": "app",
          "description": "Returns orders for the current project.",
          "read_only": true,
          "destructive": false,
          "idempotent": true,
          "result": { "kind": "data" }
        },
        "responses": {
          "200": {
            "description": "Orders",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

name starts with a Latin letter and contains 2 to 64 lowercase Latin letters, digits, or _. Write description as an instruction for AI: what the method does, when to use it, and what it returns. The read_only, destructive, and idempotent flags must match actual behavior because MCP uses them when planning a safe call.

Describe the successful response with a JSON schema. Senler gives AI both the schema and a compact list of its important fields. Without a schema, AI can read the actual JSON after calling the method but has less information about the result beforehand.

Choose The Context And Result

The context field explains the method's purpose:

Context	Purpose	Result
app	Work with data and features of the application's general page	Regular data; use kind: data
agent_tool	Prepare settings for an agent tool instance	kind: agent_tool_configuration and configuration_path
automation_step	Prepare settings for a step and its branches	kind: automation_step_configuration, configuration_path, and, when needed, branches_path

Write a result path with dots, for example result.configuration. Step branches are commonly located at result.branches. After the call, AI receives guidance about where to find these values and which Senler method saves them to the required tool or workflow node.

How MCP Finds And Calls An Action

Installed application actions do not expand the permanent MCP tool list. AI uses the shared discovery protocol:

1. call search with a short task description;
2. take the exact method_name from the result;
3. call describe_method when the compact search result does not provide enough nested input, response schema, or app_action metadata;
4. call execute with the same method_name and a parameters object that follows the returned schema.

For example, searching for “get Prodamus accounts” can return prodamus__list_accounts, while “get referral campaigns” can return reflink__list_campaigns. AI must not guess these names.

Project scope depends on the MCP connection:

Connection	How the project is determined	Is project_id needed?
Senler.io Project MCP	The project is embedded in the project OAuth token	No; a parameter cannot override it
User MCP inside a project agent or dialog	Senler supplies a signed execution context	No; AI must not request it
Direct personal User MCP connection	The selected project is not embedded in the connection	Yes; reuse the known project_id in search, describe_method, and execute

For direct User MCP, project_id is a top-level service parameter of the MCP tool. It does not belong in the action's parameters and is not forwarded to the plugin backend. See Senler.io as an MCP server for the full AI-client flow.

How The Application Backend Is Authorized

An MCP key or OAuth token authorizes the AI client only with Senler. Senler checks the project, current permissions, active installation, and exact action published in OpenAPI. The original MCP secret, OAuth token, and authorization header are never forwarded to the plugin backend.

Instead, every action call creates a short session between Senler and the application:

1. Senler signs a one-time launch_code containing the project ID, expiry, and nonce with the application's Client Secret;
2. it sends the code to /api/embedded/management-session on the same origin that hosts OpenAPI;
3. the backend verifies the signature, expiry, and nonce replay, then returns its own short-lived management_token;
4. Senler calls the marked endpoint with Authorization: Bearer <management_token>.

The session request looks like this:

POST /api/embedded/management-session
Content-Type: application/json

{"launch_code":"<one-time Senler code>"}

The application backend must verify launch_code using Client Secret and return its own short-lived token:

{"management_token":"app-session-token"}

An action has a 15-second timeout and redirects are not followed. Determine the project and permissions only from the verified management session, not from parameters supplied by AI.

The management_token is valid only in the application's own backend. If that backend then calls the Senler API, it needs its own API key or application OAuth access token with the required permissions. Neither the management_token nor the original MCP token is a Senler API credential for the plugin.

Use The SDK For NestJS

Starting with @aisenler/sdk-fetch v0.1.16, you can add the extension with ready-made decorators:

import { Get } from "@nestjs/common";
import { AppAction } from "@aisenler/sdk-fetch/app-actions/nest";

@Get("orders")
@AppAction({
  name: "list_orders",
  description: "Returns orders for the current project.",
  readOnly: true,
  destructive: false,
  idempotent: true,
  response: { status: 200, type: OrdersResponseDto },
})
listOrders() {
  // The project comes from the verified management session.
}

Use AgentToolConfigurator and AutomationStepConfigurator for configurators; they set the required context and result kind. Shared types and the framework-neutral metadata builder are exported from @aisenler/sdk-fetch/app-actions.

After generating OpenAPI, validate a local file or URL:

npx senler-app validate-openapi ./openapi.json

Validation finds invalid names and contexts, duplicates, unsupported parameters and request bodies, missing response schemas, and incorrect configuration or branch paths. Add it to the application backend's CI.

Enable Actions In The Application

For a Plugin application, open Embedded page and find the Application actions section.

1. Enable Publish actions to MCP.
2. Enter a stable method prefix from 2 to 32 characters: lowercase Latin letters, digits, and _, starting with a letter. For example, with the my_plugin prefix, the list_orders action is named my_plugin__list_orders.
3. Enter the application backend's OpenAPI JSON schema URL.
4. Click the separate Save button for this section.

Keep the prefix stable after publication: the full method name is used by AI and saved workflows. Two active installed applications in the same project must not produce the same full action name.

Test In A Project

Install and activate the plugin in a test project, connect Senler Project MCP or User MCP with permission to use applications, and give AI a task that matches a safe action marked read_only: true. Verify that:

1. the method appears under <namespace>__<name>;
2. AI sees the expected parameters and result description;
3. the backend creates a management session only for a valid launch_code;
4. the action receives the application's Bearer token and responds within 15 seconds;
5. modifying and irreversible operations have the correct safety flags.

Do not put Client Secret, management token, or private data in OpenAPI, an action description, or its parameters.

If An Action Does Not Appear

• verify that the plugin is installed and its installation is active in the selected project;
• verify that publishing is enabled and the section was saved;
• open the OpenAPI URL from a server, not only from the developer's browser;
• run senler-app validate-openapi and verify that the operation uses a supported HTTP method and the exact version 1 x-senler-app-action extension;
• wait up to 30 seconds after changing the schema;
• check that <namespace>__<name> is unique among installed applications;
• for a management-session creation error, check /api/embedded/management-session, the launch_code signature and lifetime, and the management_token response field;
• for an execution error, check the endpoint, Bearer token, backend response, and 15-second limit.