Set up Mattermost Agents (plugin mattermost-ai): connect LLMs, create agents, connect MCP servers and tools, and control access, approval, and licensing.
An agent is a Mattermost bot backed by an LLM that you choose, including a model that runs on your own infrastructure. Agents act through tools: the built-in Mattermost tools, remote MCP servers, and tools registered by other plugins. The plugin also ships a built-in Mattermost MCP server for external AI clients such as Claude Code and Cursor.
- An LLM service holds the connection to a provider: type, credentials, default model, and optional fallback. You configure services in the Agents settings.
- An agent is a bot with a name, instructions, a model, access rules, and tool grants. Agents use a service. You create them on the Agents page.
- Tools give an agent abilities. Admins decide which tools exist, which need approval, and which users can reach each MCP server.
- Users talk to agents in direct messages, the Agents pane, and channels. Every tool call runs with the permissions of the person who asked, unless an agent uses a shared service account for external MCP servers. Tools from plugin-registered servers receive the requester's identity, and the source plugin enforces its own permissions. Credentials in a remote server's regular Headers are also shared by every user. See Tool approval and credentials.
Custom instructions can't grant or restrict access. Use the agent's Access tab, MCP access policies, and tool approval policies.
| Requirement | Detail |
|---|---|
| Mattermost Server | v12.0.0 or later. |
| Site URL | Site URL must be set under System Console > Environment > Web Server. The plugin doesn't activate without it. |
| Database | The Mattermost PostgreSQL database. Agents creates its own tables and runs migrations on start. |
| pgvector | Only for semantic search. PostgreSQL needs the pgvector extension. |
| LLM access | Network access from the Mattermost Server to your LLM provider, and credentials. |
| Outbound proxy | LLM provider traffic follows the HTTP_PROXY and HTTPS_PROXY environment variables of the Mattermost Server process. |
Mattermost Server can ship with Agents pre-installed. Check System Console > Plugins > Plugin Management. To install or upgrade, download a release .tar.gz from the releases page, select Upload Plugin, and enable it. Set Enable Plugin to True under System Console > Plugins > Agents if needed.
- Open Agents from the product switcher, select Settings, and on AI services select Add an AI Service. Choose a Service type, enter the credentials and a Default model, and save. See Configure LLM services and Provider configuration. For a self-hosted model, see Sovereign AI deployments.
- Open the Agents page from the product switcher (grid icon). Select Create agent, choose a username, the service, and optional instructions. See Create and manage agents.
- Back in Agents > Settings > General, pick the Default bot. Users who haven't chosen an agent get this one, and so do features that don't let users choose, such as meeting summaries. If the default agent becomes unavailable, those features fail until you pick another. Mattermost never substitutes a different agent.
- Send the agent a direct message to test it.
- Optionally add MCP servers, web search, or semantic search, and set access controls.
| I want to | Go to |
|---|---|
| Connect an LLM provider, set fallbacks and token limits | Configure LLM services, Provider configuration, AWS Bedrock |
| Create agents, delegate agent management, export and import agents | Create and manage agents |
| Restrict who can use an agent, service, or MCP server | Control who can use agents |
| Connect remote MCP servers and let agents use tools | Connect agents to MCP servers |
| Decide which tool calls need approval | Tool approval and credentials |
| Control tools, auto-reply, and web search in channels | Control agents in channels |
| Let external AI clients use Mattermost | External client endpoint |
| Give agents web search | Web search |
| Turn on semantic search | Set up semantic search |
| Control links and HTML in AI output | Secure AI-generated links and HTML |
| Know what is sent to the LLM and what is stored | Data handling |
| Track usage, tracing, and audit events | Monitor Agents |
| Back up Agents or automate configuration | Back up and automate |
| Run fully self-hosted or air-gapped | Sovereign AI deployments |
| Fix a problem | Troubleshooting |
| Upgrade from Agents 1.x | Upgrade from Agents 1.x |
For developers and integrators, see the Mattermost MCP server for connecting Claude Code or Cursor, the tool reference, and the LLM Bridge for plugins.
System admins can always view and change the Agents settings. To let other people in, go to System Console > Plugins > Agents, add them under Settings access, and select Save:
- Read and write access: can view and change every Agents setting, including API keys, run reindexing, and author service and MCP server access policies. They can also turn on service account authentication for agents they manage. Because they choose which AI services and MCP servers agents use, they can send what users say to agents, including private messages, to a service they control. Grant this only to people you would trust as an Agents system admin. They can't change who has access or the legacy agents defined in the plugin configuration.
- Agent managers: can edit and delete every agent, as the
manage_others_agentpermission allows, without any access to the settings.
People with read and write access see Settings in the Agents sidebar. Access is per user; Mattermost's delegated admin roles don't grant it. Only a system admin can change the lists.
Everything is under Agents > Settings, in the General, AI services, MCP servers, Embedding search, Web search, and Debug sections. System Console > Plugins > Agents has an Open Agents settings button and the Settings access lists below. The plugin stores its configuration, and agents, in its own database tables. See Back up and automate.
| Panel | Setting | Config key | Default | Details |
|---|---|---|---|---|
| AI Services | Services | services |
none | Configure LLM services |
| AI Bots | Limit agent version history, Versions to keep per agent | agentVersionsToKeep |
Off (0, keep all). Turning it on sets 50. |
Create and manage agents |
| AI Functions | Default bot | defaultBotUserID |
The first agent, until you pick one | Create and manage agents |
| AI Functions | Render AI-generated links | allowUnsafeLinks |
Off | Secure AI-generated links and HTML |
| AI Functions | Allowed Link Domains (csv) | allowedLinkDomains |
Empty (any domain, when links are on) | Secure AI-generated links and HTML |
| AI Functions | Enable HTML artifacts (experimental) | enableHTMLArtifacts |
Off | Secure AI-generated links and HTML |
| AI Functions | Enable Channel Mention Tool Calling (experimental) | enableChannelMentionToolCalling |
Off | Control agents in channels |
| AI Functions | Enable ambient auto-replies (experimental) | enableAmbientAutoReply |
Off | Control agents in channels |
| AI Functions | Allow native web search in channels | allowNativeWebSearchInChannels |
Off | Control agents in channels |
| Debug | Trace Output, OpenTelemetry Endpoint, Use TLS for OTLP Export, OTLP Export Headers | telemetryOutput, openTelemetryEndpoint, openTelemetryTLS, openTelemetryHeaders |
Off | Monitor Agents |
| Debug | Enable Token Usage Logging | enableTokenUsageLogging |
Off | Monitor Agents |
| Embedding Search (experimental) | Embedding settings and reindex controls | embeddingSearchConfig |
Off | Set up semantic search |
| Web Search | Built-in web search | webSearch |
Off | Web search |
| Model Context Protocol (MCP) | Servers, tools, HTTP endpoint, idle timeout | mcp |
HTTP endpoint off, idle timeout 30 minutes | Connect agents to MCP servers |
The plugin distinguishes four license levels: Free (no license), Professional, Enterprise, and Enterprise Advanced. Each level includes everything below it. The Entry license behaves as Enterprise. Legacy E10 licenses count as Professional and E20 licenses as Enterprise. A development server (EnableDeveloper and EnableTesting both on) enables every capability.
| Capability | Free | Professional | Enterprise | Enterprise Advanced |
|---|---|---|---|---|
| Agents | 1 | 3 | Unlimited | Unlimited |
| LLM services | 1 | 1 | Multiple | Multiple, with fallback chains |
| Direct messages with an agent | Yes | Yes | Yes | Yes |
| Vision and document attachments | Yes | Yes | Yes | Yes |
| Personal skills | Yes | Yes | Yes | Yes |
| Built-in Mattermost tools | Read-only | Read-only | Read and write | Read and write |
| Agents in channels (@mention) | No | Yes | Yes | Yes |
| Thread, channel, and unread summaries | No | Yes | Yes | Yes |
| Provider-native web search | No | Yes | Yes | Yes |
| Agent access controls (users, teams, channels) | No | Yes | Yes | Yes |
| Token usage logging | No | Yes | Yes | Yes |
| Built-in web search (Brave, Google, SearXNG) | No | No | Yes | Yes |
| Tool approval policies | No | No | Yes | Yes |
| Remote and external MCP servers, HTTP MCP endpoint | No | No | Yes | Yes |
| MCP service account authentication | No | No | Yes | Yes |
| Semantic search and AI search | No | No | Yes | Yes |
| Meeting summaries | No | No | Yes | Yes |
| Shared skills | No | No | Yes | Yes |
| Channel auto-reply | No | No | No | Yes |
| Attribute-based access control | No | No | No | Yes |
- Agent cap. Configuration-file bots and user-created agents share one pool. Over the cap, the plugin activates configuration-file bots first, then user-created agents oldest first. The rest stay stored but inactive, marked Inactive on the Agents page and named in the server log. Creating an agent over the cap fails with a message naming the level that raises it.
- One service below Enterprise. Free and Professional use only the first service in the list. Agents that use another service are inactive and don't count toward the agent cap. LLM Bridge calls reach only the first service.
- HTTP MCP endpoint. What happens to an endpoint that is already on after a downgrade is in External client endpoint.
- Fallback chains. Followed at Enterprise Advanced only. Below that, a stored fallback stays in the configuration but requests use the primary service.
- Write tools. Tools that change something in Mattermost (post, react, edit, create channels, and similar) are absent from the tool list below Enterprise, and calls return a licensing message.
- Approval policies. Below Enterprise, built-in Mattermost tools use the product defaults and every other tool that has a policy asks first. Tools without a policy are listed in Approval policies. A stricter policy you set earlier still applies. A disabled tool stays disabled.
- Reading configuration is never blocked.
- Turning something off is never blocked. You can disable, clear, or delete a gated setting after a license downgrade.
- License changes apply without restarting the plugin.
- A System Console or REST API request denied for licensing returns HTTP 403 with an
errormessage and alicense_requiredfield set toprofessional,enterprise, orenterprise_advanced. LLM Bridge completions, MCP tools, and channel mentions report licensing differently. See LLM Bridge.