Action Definitions

Prepare The Backend And OpenAPI

Publish OpenAPI 3 JSON at a public HTTPS address on the application backend. An external application cannot use localhost, private-network addresses, or URLs containing a username or password. Senler does not follow redirects, waits up to 5 seconds for the schema, and accepts a document up to 5 MiB. The loaded schema is cached for about 30 seconds, so a change may not appear in the catalog immediately.

Host the schema and handlers on the same origin: the same protocol, domain, and port. For example, with the schema at https://plugin.example.com/openapi.json, the path /api/orders is called as https://plugin.example.com/api/orders. The OpenAPI servers field does not override this address. Operation paths start with /; a full URL or a redirect to another server is not used.

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

For actions available through MCP, 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.

Funnel Reports

A plugin funnel data source uses a separate funnel context with the funnel_report result. This method only reads data: set read_only: true and do not mark it as destructive. It is called when fetching a report for the connected source. The request and response formats and record-to-lead matching are described in the report method contract.

The installed application action catalog used by search, describe_method, and execute currently supports only the three contexts in the table above. A funnel method in OpenAPI therefore does not mean that AI can find it as a separate plugin action through MCP.

In @senlerio/api version 0.4.0, decorators from @senlerio/api/app-actions/nest and the senler-app validate-openapi command also support only these three contexts. For a funnel report, define x-senler-app-action directly in OpenAPI. An unsupported funnel error from this CLI version does not mean that Senler rejects the report method; this CLI does not cover its validation.

Next Step

Implement backend authorization, then connect OpenAPI in the cabinet.