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.

Connection URLs

For an external AI client such as Codex, use one of these public Senler.io HTTPS endpoints:

Project MCP: https://mcp-senler-io.senler.io/mcp — work with one project selected during authorization.
User MCP: https://mcp-senler-io-user.senler.io/mcp — act on behalf of a user across their accessible projects and developer applications.

Both endpoints accept MCP requests, including initialize, over Streamable HTTP. A direct external connection without a token is prompted to use OAuth. The connection is direct: no custom intermediary server or local MCP bridge is required. Project MCP also works with external clients; using Codex does not by itself require User MCP.

Each URL is shared by all users, not generated for an individual project. Copy the appropriate address above into your AI client's MCP server settings. You do not need to find it in the Cabinet menu, create an application in the developer area, or add a server to a Senler agent's settings.

For public documentation only, without signing in, add ?auth_mode=public, for example https://mcp-senler-io-user.senler.io/mcp?auth_mode=public. Documentation search and reading are available, but project data is not. If the client sends X-Auth-Mode: oauth, it still requests OAuth; that header is not needed for public mode. An invalid token is rejected even with auth_mode=public.

Connecting Through OAuth

In your AI client, add a remote MCP server with the appropriate URL above and the Streamable HTTP transport.
Start OAuth sign-in. The client opens the Senler.io authorization page.
Sign in to your Senler.io account. For Project MCP, choose a project; for User MCP, authorize access on behalf of your user. Review the requested permissions before confirming.
Return to your AI client and check that MCP tools are available.

A client supporting OAuth discovery and dynamic client registration obtains the authorization and token endpoints from the MCP server. You do not need to create a Client ID manually or copy a Client Secret or Senler API key for this flow.

When implementing your own MCP client, OAuth metadata is available at the standard paths /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server on the selected server's domain. /authorize, /token, and /register are OAuth endpoints; /mcp handles MCP requests. Neither https://api.senler.io nor https://senler.io/oauth/authorize replaces the MCP URL.

Codex Example

For a ready-made connection, install and enable the Senler.io User plugin for Codex. It connects User MCP and includes guidance for first-time sign-in and working with Senler. Adding the plugin marketplace alone is not enough: the plugin itself must be installed and enabled.

In a new chat, ask: "Connect Senler.io User and show the projects I can access. Do not change anything yet." Complete OAuth sign-in when the client asks, then choose a project. Successfully reading the list confirms the connection but does not grant additional editing permissions. Do not send tokens in chat.

Without a plugin, you can configure MCP directly. To work with one project:

codex mcp add senler-project --url https://mcp-senler-io.senler.io/mcp
codex mcp login senler-project

To act on behalf of a user, including managing developer applications:

codex mcp add senler-user --url https://mcp-senler-io-user.senler.io/mcp
codex mcp login senler-user

Choose the appropriate option; configuring both connections is not required. Instead of the add command, you can define a server in ~/.codex/config.toml. A minimal User MCP example without secrets:

[mcp_servers.senler-user]
url = "https://mcp-senler-io-user.senler.io/mcp"

After manual configuration, also run codex mcp login senler-user. Use codex mcp list to check configured connections. Client options are described in the Codex MCP documentation.

Plan Availability

Project MCP and User MCP are available on Trial, Start, and Big Agent: the MCP connection itself has no separate plan restriction. Actions performed through MCP follow user permissions, granted OAuth scopes, and the project's usual limits. See Plans and limits for plan features and pricing.

An external AI client consumes the daily API quota when MCP accesses project data. The quota is shared with the project's API keys and other external integrations. On api.daily_quota_exceeded, wait for the reset or increase the limit: reconnecting MCP does not reset usage.

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. For a regular external client, follow the OAuth instructions above. An MCP access key such as mcp_sk_…, linked to saved authorization, can also serve as a connection secret, but obtaining one separately is not required for Codex OAuth sign-in. If your integration uses such a key, never put it in an agent request, documentation, or method parameters.

When an MCP access key is linked to Senler.io Project MCP or User MCP OAuth authorization and a refresh_token is saved, the expiring access token is refreshed automatically on access. This does not extend the MCP access key itself or restore revoked access. Reconnect if the key has expired or authorization has been revoked; signing in again for every routine access token refresh is not required.

A 503 response with temporarily_unavailable or Session store unavailable means the MCP authorization service is temporarily unavailable, not that permission was denied. Retry after the delay in Retry-After; this error does not require granting permissions again. For a command that changes data, first check the previous attempt's result: an arbitrary 503 response alone does not prove that the action did not execute.

Senler.ru Bot Configuration

Senler.io Project MCP and User MCP cannot read the full configuration of an existing Senler.ru bot: blocks, connections, conditions, message texts, model settings, and System and User prompts. There is no Senler.ru API or built-in export, or Senler.io MCP method, for retrieving this full configuration.

Linking a Senler.ru channel lets you import leads but does not provide access to bot configurations. Reconnecting or granting more OAuth permissions does not add this capability.

After connecting

To let Hermes react to project events as well as carry out your requests, connect the Senler plugin and a Hermes subscription. This does not require a public webhook receiver.

Continue with calling methods: finding an action, reading its schema, passing the project, and checking the result. To develop your own plugin methods, see Application actions.