Senler.io as an MCP Server

Senler can act not only as a client of an external MCP server but also as an MCP server for an external AI client. In this mode, AI reads and changes Senler data and calls permitted actions from plugins installed in the project.

This is the reverse of the regular MCP servers flow: that section connects an external server to a Senler agent, while this flow connects an external AI client to Senler.

Project MCP And User MCP

Connection	Access scope	How the project is determined
Senler.io Project MCP	One project and the OAuth permissions granted for it	`project_id` is embedded in the project OAuth token
Senler.io User MCP	The user and resources permitted to that user	A direct personal connection selects the target project for the request; inside an agent or dialog, the project comes from a signed Senler context

Project MCP is suitable when an external application must work only with one connected project. Another ID in text or parameters cannot change that connection's project.

User MCP operates on behalf of a user. It can authenticate with user OAuth or an MCP access key such as mcp_sk_… linked to saved authorization. Pass the key only as a connection secret; never put it in an agent request, documentation, or method parameters.

Tools Available To AI

To avoid sending thousands of Senler and installed-application methods to the model at once, MCP keeps a compact discovery tool set. User MCP also uses these tools to discover methods that manage the user's developer applications:

Tool	When to use it
`search`	Find Senler API methods and installed application actions for a task.
`describe_method`	Get the full parameter and response schema plus metadata for one exact method.
`execute`	Call an exact method returned by `search`.
`search_documentation`	Find documentation about behavior, settings, and limits.
`get_documentation_page`	Read a full page using an exact `document_ref` from search.

Some MCP clients can expose a discovered method dynamically as a separate tool. AI can call that exact tool directly in such a client. A client may also show connection-status helpers, but this does not change the main discovery protocol.

For a “how do I configure this?” question, AI uses search_documentation and then get_documentation_page. To read or change actual data, it uses search, optionally describe_method, and then execute.

Calling A Method

AI must not invent a method name or visual-form fields. The correct sequence is:

pass a short task description to search;
select an exact method_name only from the search response;
call describe_method when nested fields, a detailed response schema, or app_action metadata is needed;
pass that name to execute and method arguments as a flat parameters object;
after a mutation, read the entity again when a suitable verification method exists.

Use concise Russian terms in search because most Senler API method descriptions are in Russian.

For example, in Project MCP:

{"query":"получить аккаунты Prodamus"}

Search can return prodamus__list_accounts. When the available metadata is sufficient, call it as follows:

{
  "method_name": "prodamus__list_accounts",
  "parameters": {}
}

For RefLink, a similar search can return reflink__list_campaigns. The developer defines the prefix before __, so AI always takes the full name from the current search response instead of constructing it.

User MCP can also create and configure applications owned by the developer. The complete workflow, the appId versus project_id distinction, draft rules, and manual steps are covered in Developing an Application Through User MCP.

Passing project_id

Do not pass project_id to search, describe_method, or execute for Project MCP: the server reads it from the verified project OAuth token.

User MCP has two modes:

when User MCP is called by an agent or dialog inside a project, the project already exists in the signed execution context, so project_id is not needed;
for a direct personal User MCP connection, use the already-known target project_id in search, then repeat the same ID in describe_method and execute for an installed application method.

Direct User MCP example:

{
  "query": "получить реферальные кампании",
  "project_id": "<project ID>"
}

{
  "method_name": "reflink__list_campaigns",
  "project_id": "<the same project ID>",
  "parameters": {}
}

Here, project_id is a top-level service parameter of the MCP tool, not a field in the plugin's parameters. The action itself must not declare project_id in OpenAPI.

Passing An Application ID

An application ID is not required. search receives a task description, not an application ID. Senler automatically adds actions from all active applications installed in the selected project. To narrow the search, mention a recognizable application name or action, such as “Prodamus accounts” or “RefLink campaigns.”

An action appears only when:

the plugin is installed and active in the target project;
the developer enabled action publishing and supplied a reachable OpenAPI URL;
the operation has x-senler-app-action metadata;
the current connection has can_use_project_apps.

The can_use_project_apps permission, shown as Use installed applications, is sufficient to call an action. can_manage_project_apps covers installing, changing, and removing applications and is not independently required for an action call. If the permission was added to an OAuth policy after connecting, complete OAuth again: expanding a policy does not add scopes to an existing token.

How AI Configures Application Forms

The action OpenAPI replaces a visual form that AI cannot inspect:

context: app describes regular work with data on an embedded or main application page;
context: agent_tool returns validated, normalized agent-tool configuration;
context: automation_step returns step configuration and, when needed, its branches.

For the last two contexts, AI first calls the application configurator according to its schema, then saves the value at app_action.result.configuration_path and branches at branches_path with the matching Senler API method. It must not guess visual-form fields or call the configurator again while a published automation is running.

How MCP Is Authorized With A Plugin

The external AI client's token works only between the client, MCP, and the Senler API. The plugin backend never receives an MCP access key, user OAuth token, or project OAuth token.

The call chain is:

AI client → Senler MCP → Senler API → plugin management session → action endpoint

After validating the project, can_use_project_apps, active installation, and OpenAPI, Senler creates a signed one-time launch_code. The application backend verifies it with its Client Secret and returns its own short-lived management_token. Senler sends only this token to the action endpoint as Authorization: Bearer <management_token>.

If the plugin backend then calls the Senler API itself, it needs a separate API key or application OAuth access token with the required permissions. Neither management_token nor the original MCP token is used to call the Senler API. See Application Actions for implementation details.

When A Method Is Missing Or Unavailable

retry search with short Russian terms and close synonyms because most API method descriptions are in Russian;
do not execute an invented name after an empty search;
for direct User MCP, verify that the same project_id is used for action discovery and execution;
verify that the plugin is installed and active in the required project;
check can_use_project_apps in the current token, not only in the application's current OAuth policy;
after changing OpenAPI, wait up to 30 seconds and search again;
when describe_method cannot find a name, first obtain it again through search in the same project.