From 0197fcfb104ff468845ab99d2eb6abf9b8d1836e Mon Sep 17 00:00:00 2001 From: Harshil Sharma Date: Fri, 14 Aug 2026 11:08:39 +0530 Subject: [PATCH 1/6] Post delivery audit logs first draft --- source/_generated/agents/docs/admin_guide.md | 323 +++++++++++++----- source/_generated/agents/docs/user_guide.md | 105 +++++- .../compliance-with-mattermost.rst | 4 +- .../comply/embedded-json-audit-log-schema.rst | 13 + .../comply/post-delivery-audit-logging.rst | 211 ++++++++++++ .../environment-configuration-settings.rst | 1 + .../configure/site-configuration-settings.rst | 78 +++++ .../manage/admin/content-flagging.rst | 39 +++ .../administration-guide/manage/logging.rst | 12 +- 9 files changed, 689 insertions(+), 97 deletions(-) create mode 100644 source/administration-guide/comply/post-delivery-audit-logging.rst diff --git a/source/_generated/agents/docs/admin_guide.md b/source/_generated/agents/docs/admin_guide.md index b86fc4d5a67..c63ff04b8c7 100644 --- a/source/_generated/agents/docs/admin_guide.md +++ b/source/_generated/agents/docs/admin_guide.md @@ -12,6 +12,7 @@ Before installing the Agents plugin, ensure your environment meets these require - PostgreSQL database - For semantic search: PostgreSQL with pgvector extension - Network access to your chosen LLM provider +- If outbound LLM traffic must use an HTTP proxy, set `HTTP_PROXY` and `HTTPS_PROXY` on the Mattermost server process or container environment. - API keys if using a cloud LLM service ### Installation Steps @@ -22,7 +23,7 @@ From Mattermost v10.3, Agents comes installed automatically and ready for you to #### Install latest version -For the most recent features and improvements, you can download and install the latest plugin version from the [GitHub releases page](https://github.com/mattermost/mattermost-plugin-ai/releases). +For the most recent features and improvements, you can download and install the latest plugin version from the [GitHub releases page](https://github.com/mattermost/mattermost-plugin-agents/releases). Install the plugin through the System Console by navigating to **System Console > Plugin Management**, clicking **Upload Plugin**, selecting the downloaded plugin file (.tar.gz), and clicking **Upload**. Enable the plugin after upload completes, then configure plugin settings as detailed in the Configuration section below. @@ -30,7 +31,9 @@ Install the plugin through the System Console by navigating to **System Console ### Access plugin settings -Navigate to **System Console > Plugins > Agents** to access the configuration interface. +Navigate to **System Console > Plugins > Agents** to configure plugin-wide settings such as AI services, the default bot, web search, embedding search, and MCP settings. + +Create and manage agents from the top-level **Agents** product page. You can also open it from **AI Actions > Manage agents**. The **AI Bots** section in the System Console links to the Agents page instead of hosting the full agent editor. ### Enable the plugin @@ -40,7 +43,21 @@ Agents is enabled automatically when using the pre-installed version. If you've If you have an Enterprise, or Enterprise Advanced license, upload it to unlock additional features. If you don't have a license but are running Mattermost Enterprise Edition, an Entry license will be automatically applied for you. -For general settings, you can toggle to enable or disable the plugin system-wide, enable debug logging for troubleshooting (use only when needed), enable token usage logging for tracking LLM interactions, and configure the hostname allowlist for API calls. +For general settings, you can toggle to enable or disable the plugin system-wide, enable debug logging for troubleshooting (use only when needed), enable token usage logging for tracking LLM interactions, and configure the hostname allowlist for API calls. Outbound LLM provider traffic respects `HTTP_PROXY` and `HTTPS_PROXY` when they are set on the Mattermost server process. + +### AI response link rendering + +Mattermost Agents includes a setting that controls whether AI-generated Markdown links are rendered as clickable links in responses: + +- **System Console label**: **Render AI-generated links** +- **Configuration key**: `allowUnsafeLinks` +- **Default value**: `false` + +When **Render AI-generated links** is set to **False** (default), AI-generated Markdown links are shown as plain text and are not rendered as clickable links. + +When this setting is set to **True**, AI-generated links may be rendered as clickable links. This is a security tradeoff: AI output can include malicious destinations, which can increase phishing and data exfiltration risk. + +Enable this setting only in trusted or otherwise mitigated environments, such as where users are trained to validate links and your organization has endpoint protections and URL controls in place. ### Service configuration @@ -51,14 +68,14 @@ Navigate to **System Console > Plugins > Agents** and select **Add a Service**. | Setting | Description | |---------|-------------| | **Name** | Internal name for this service configuration | -| **Type** | LLM provider (OpenAI, Anthropic, AWS Bedrock, Cohere, Mistral, Azure OpenAI, OpenAI-compatible) | +| **Type** | LLM provider (OpenAI, Anthropic, AWS Bedrock, Cohere, Mistral, Scale AI, Azure OpenAI, OpenAI-compatible) | | **API Key** | Your provider's API key (requirements vary by provider) | | **Default Model** | Default model to use for this service | | **Input Token Limit** | Maximum tokens allowed in input | | **Output Token Limit** | Maximum tokens allowed in output | | **Streaming Timeout Seconds** | Timeout in seconds for streaming responses | | **Send User ID** | Whether to send Mattermost user IDs to the LLM provider | -| **Use Responses API** | (OpenAI/Compatible only) Enable OpenAI's Responses API for richer tool integration | +| **Use Responses API** | (OpenAI Compatible and Azure OpenAI only) Use OpenAI's Responses API for native provider tools, reasoning controls, and structured output on those endpoints. OpenAI (direct) always uses the Responses API, so this control isn't shown for that service type. | #### Provider Specific Settings @@ -66,47 +83,85 @@ Each provider has specific configuration requirements: | Provider | Required Settings | Optional Settings | |----------|-------------------|-------------------| -| **OpenAI** | API Key | Organization ID, API URL (for compatible services) | +| **OpenAI** | API Key | Organization ID | +| **OpenAI Compatible** | API URL | API Key, Organization ID | | **Anthropic** | API Key | | | **AWS Bedrock** | AWS Region | API Key (can use IAM role), Access/Secret Keys | | **Cohere** | API Key | | | **Mistral** | API Key | | +| **Scale AI** | API Key, API URL | Account ID (required for ScaleGov) | | **Azure OpenAI** | API Key, API URL | | For AWS Bedrock, authentication can be configured using AWS credentials in the API Key/Secret fields, or by using IAM roles when running Mattermost on AWS infrastructure. **Important for Anthropic Claude models**: Before using Claude models via AWS Bedrock, you must submit a one-time First Time Use (FTU) form in the AWS Bedrock Model Catalog, and attach Bedrock API permissions to your Mattermost servers' IAM role. See the [AWS Bedrock setup guide](https://docs.mattermost.com/agents/docs/aws_bedrock_setup.html) for detailed instructions. +OpenAI services always use the Responses API. OpenAI Compatible and Azure services keep the **Use Responses API** setting so you can disable it for endpoints that still require legacy Chat Completions compatibility. + See the [Provider Guide](https://docs.mattermost.com/agents/docs/providers.html) for detailed provider-specific configuration. ### Agent configuration -Create an Agent (Bot) that uses a configured Service. Multiple Agents can use the same Service configuration. See [license requirements](#license-requirements) for details on features that require a license. +Create and manage agents from the **Agents** product page. Open it from the top-level **Agents** product entry or from **AI Actions > Manage agents**. Agents use the service inventory configured in **System Console > Plugins > Agents**, and multiple agents can reuse the same service configuration. See [license requirements](#license-requirements) for details on features that require a license. + +If you can manage an agent, select its row in the Agents list to open the full-page configuration view directly. The overflow menu remains available for **Edit** and **Delete**. Use **Back to agents** to return to the list. + +When you create or edit an agent, use the three tabs in the full-page agent configuration view: + +- **Configuration** for identity, model selection, instructions, and core capabilities +- **Access** for channel, team, and user restrictions, plus delegated agent admins +- **MCPs** for the agent's allowed MCP tools -Navigate to **System Console > Plugins > Agents** and select **Add an Agent**. +If you have unsaved changes and try to leave the agent configuration view by selecting **Back to agents**, **Cancel**, or by pressing Escape, Mattermost shows a **Discard changes?** confirmation with **Discard** and **Keep editing**. + +#### Configuration tab | Setting | Description | |---------|-------------| | **Display Name** | User-facing name shown in Mattermost | -| **Agent Username** | The mattermost username for the agent. @ mentions to the agent will use this name | +| **Agent Username** | The Mattermost username for the agent. @mentions use this name. Set it when creating the agent; it can't be changed later. | | **Agent Avatar** | Custom image for the agent | | **Service** | Select a configured Service from the dropdown | | **Model** | (Optional) Override the service's default model for this agent | | **Custom Instructions** | Custom instructions that define the agent's personality and capabilities | | **Enable Vision** | Enable Vision to allow the agent to process images. Requires a compatible model and service. | -| **Enable Tools** | By default some tool use is enabled to allow for features such as integrations with JIRA. Disabling this allows use of models that do not support or are not very good at tool use. Some features will not work without tools. | -| **Access Control** | Set which teams, channels, and users can access this agent | +| **Enable Tools** | Enables tool use for integrations and other tool-based capabilities. Disable this only for models or use cases where tool calling shouldn't be available. Some features won't work without tools. | #### LLM Specific Agent Settings -Some capabilities are available depending on the selected Service and its configuration: +Some capabilities depend on the selected Service type and, for OpenAI Compatible and Azure, whether **Use Responses API** is enabled on that service. | Setting | Description | |---------|-------------| -| **Enable Web Search** | Available for OpenAI (with Responses API enabled on the Service) and Anthropic. Allows the Agent to leverage the provider's native web search tool to respond with recent information. | -| **Reasoning Enabled** | Available for OpenAI (with Responses API) and Anthropic. Enables "thinking" or reasoning capabilities for complex tasks. | +| **Enable Web Search** | Available for Anthropic, OpenAI, Google Gemini, and Google Vertex AI. For OpenAI Compatible and Azure, this setting is available when **Use Responses API** is enabled on the Service. Gemini and Vertex map this to Google Search grounding via the provider's Responses API. Allows the Agent to leverage the provider's native web search tool to respond with recent information. | +| **Reasoning Enabled** | Available for Anthropic, OpenAI, Google Gemini, and Google Vertex AI. For OpenAI Compatible and Azure, this setting is available when **Use Responses API** is enabled on the Service. Enables extended thinking or reasoning capabilities for complex tasks. For Gemini / Vertex, Bifrost maps a token budget to `thinkingConfig.thinkingBudget` and an effort level to `thinkingConfig.thinkingLevel` on Gemini 3.0+. | +| **Structured Output** | Available for Anthropic, OpenAI, OpenAI Compatible, and Azure. When enabled and a JSON schema is provided in the request, the model returns structured JSON matching that schema. Compatible model support is still required. | + +New agents enable native web search and structured output by default where the selected provider supports those features. For providers that don't support native tools, native tool selections are ignored. + +For Anthropic services, **Structured Output** and extended thinking can't be used at the same time. + +If you need an OpenAI-style endpoint without the Responses API path, use an **OpenAI Compatible** service and turn **Use Responses API** off for that service instead of using the **OpenAI** service type. + +#### Access tab + +Use this tab to control who can interact with and manage the agent: + +- **Channel access** controls which channels the agent can be mentioned in +- **User access** controls which users can interact with the agent +- **Agent admins** can edit and delete the agent; the agent creator is always an admin + +#### MCPs tab + +Use this tab to control which MCP tools the agent can use. This tab is available only when **Enable Tools** is turned on. + +- **Automatically enable all MCP tools** gives the agent access to every currently available MCP tool and any MCP tools added later. +- When **Automatically enable all MCP tools** is off, select the specific MCP tools the agent may use. +- If a previously selected MCP tool is no longer available, it is removed from the agent configuration when you save. -Select **Save** to create the agent. +Updating an agent's display name also updates the linked Mattermost bot display name. Deleting an agent deactivates the linked Mattermost bot account. + +Legacy bots previously stored in plugin configuration are migrated on startup into database-backed agents and then managed from the **Agents** page. Migrated agents don't have a creator and can be managed by system admins. ### Custom instructions @@ -116,17 +171,17 @@ For example, you could list your organization's specific acronyms so the agent k ### Built-in web search configuration -The built-in web search tool allows agents to retrieve current information from the internet when answering user questions. This feature is designed for deployments using LLM models that don't provide their own native web search capabilities. +The built-in web search tool lets agents retrieve current information from the internet when the model or deployment doesn't use the provider's own search. Prefer native provider web search when your service supports it. #### When to use built-in web search -Built-in web search is intended for LLM models that lack native web search functionality. If your chosen model already provides native web search (such as OpenAI with the Responses API or Anthropic's native search tool), it's strongly recommended to use the provider's native implementation instead. Native web search tools typically offer: +Built-in web search is intended for LLM models that lack native web search functionality. If your chosen model already provides native web search (such as OpenAI, Anthropic, Google Gemini, Google Vertex AI, or an OpenAI Compatible/Azure service with **Use Responses API** enabled), it's strongly recommended to use the provider's native implementation instead. Native web search tools typically offer: - Better integration with the model - More reliable search results - Optimized performance -For configuration details on native web search with supported providers, see the [LLM Specific Settings](#llm-specific-settings) section above. +For configuration details on native web search with supported providers, see the [LLM Specific Agent Settings](#llm-specific-agent-settings) section above. #### Provider comparison @@ -219,7 +274,6 @@ Configure chunking options based on your needs: | **Chunking Strategy** | Sentences, Paragraphs, or Fixed Size | Choose based on your content type | | **Chunk Size** | 512-1024 tokens | Varies by strategy | | **Chunk Overlap** | 20-50 tokens | For better context continuity | -| **Minimum Size Ratio** | Default | Minimum ratio for chunk size validation | Run the initial indexing process after configuration. @@ -281,21 +335,124 @@ Post indexing occurs automatically during initial setup and when changing embedd - Trigger reindexing when changing embedding providers. - Check indexing status. +### OpenTelemetry tracing + +The plugin supports distributed tracing via [OpenTelemetry](https://opentelemetry.io/) to provide visibility into request latency, LLM call performance, tool execution, and error diagnosis. + +#### What gets traced + +When enabled, the plugin creates spans for: + +- **HTTP requests**: Every API call to the plugin, with method, route, and status code (via otelgin middleware) +- **LLM completions**: Provider, model, operation type, streaming status, input/output token counts, and errors +- **Tool execution**: Tool name, ID, resolution status, and errors for both built-in and MCP tools +- **MCP tool calls**: Remote MCP server and tool name +- **Semantic search**: Search queries and result retrieval +- **Web search**: Brave and Google search API calls +- **Post streaming**: Duration and context for streaming LLM responses to posts + +Spans are organized in a parent-child hierarchy that follows the request flow, so a single user message produces a trace like: + +```text +HTTP POST /post/:postid/react + └── process user request + ├── llm chat completion (provider=openai, model=gpt-4o, tokens=150/42) + ├── resolve tool (tool=web_search) + └── stream to post +``` + +#### Enabling tracing + +The plugin offers three trace output modes, configurable via **Trace Output** in the System Console: + +- **Off** — tracing disabled, zero overhead. +- **Server Logs** — finished spans are written to the Mattermost server log via the standard plugin logger. No collector required; pick this if you don't run Tempo, Jaeger, or another OTLP backend. +- **OTLP Endpoint** — spans are exported over OTLP gRPC to the endpoint configured in **OpenTelemetry Endpoint** (e.g. `localhost:4317`). Use this for full distributed tracing with a backend like Grafana Tempo or Jaeger. + +The setting can also be configured directly in the plugin configuration JSON: + +```json +{ + "telemetryOutput": "otlp", + "openTelemetryEndpoint": "your-collector:4317" +} +``` + +Valid values for `telemetryOutput` are `off`, `logs`, and `otlp`. When set to `off` (or omitted), the plugin uses a no-op tracer with zero overhead. The `openTelemetryEndpoint` field is only consulted when the mode is `otlp`. + +#### Local development with Grafana Tempo + +For local development and debugging, use the included Docker Compose file to run [Grafana Tempo](https://grafana.com/oss/tempo/) and Grafana: + +```bash +docker compose -f dev/docker-compose.otel.yml up -d +``` + +This starts: +- **Tempo** with OTLP gRPC on port `4317` and OTLP HTTP on port `4318` +- **Grafana** at `http://localhost:3001` with the Tempo datasource preprovisioned (anonymous Admin, no login required) + +Configure the plugin with endpoint `localhost:4317`, then interact with the bot. Open Grafana → **Explore** → **Tempo** and search by service name `mattermost-ai-agents`, or paste a trace ID directly. + +Grafana is mapped to port `3001` (not the default `3000`) so it does not collide with Mattermost's webapp dev server or the `mattermost-server` build/docker-compose stack. + +To stop the stack: + +```bash +docker compose -f dev/docker-compose.otel.yml down +``` + +Add `-v` to also discard accumulated traces. + +#### Production deployment + +For production, send traces to your existing OpenTelemetry Collector or directly to a backend: + +- **OpenTelemetry Collector**: Point the endpoint to your collector's OTLP gRPC address. The collector can then export to Jaeger, Zipkin, Datadog, Grafana Tempo, AWS X-Ray, or any other supported backend. +- **Direct export**: Point the endpoint directly to a backend that supports OTLP gRPC (e.g., Grafana Tempo at `tempo:4317`). + +The connection currently uses insecure (non-TLS) gRPC. For TLS-terminated endpoints, route through an OpenTelemetry Collector with TLS configured. + +#### Custom span attributes + +Traces include these semantic attributes for filtering and analysis: + +| Attribute | Description | Example | +|-----------|-------------|---------| +| `agents.llm.provider` | LLM provider name | `openai`, `anthropic` | +| `agents.llm.model` | Model identifier | `gpt-4o`, `claude-3-opus` | +| `agents.llm.operation` | Operation type | `conversation`, `title_generation` | +| `agents.llm.input_tokens` | Input token count | `150` | +| `agents.llm.output_tokens` | Output token count | `42` | +| `agents.tool.name` | Tool being called | `web_search`, `read_channel` | +| `agents.tool.id` | Tool call identifier | `call_abc123` | +| `agents.mcp.server` | MCP server name | `github-server` | +| `agents.mcp.tool` | MCP tool name | `search_issues` | +| `agents.user.id` | Requesting user ID | `abc123def456` | +| `agents.channel.id` | Channel ID | `abc123def456` | +| `agents.post.id` | Post ID | `abc123def456` | +| `agents.thread.root_post.id` | Root post ID for thread correlation | `abc123def456` | + ### Backup and restore -The plugin configuration is stored in the Mattermost database. To backup: +The plugin stores agent data across both plugin configuration and plugin database tables. To backup: + +1. Ensure your regular Mattermost backup includes plugin configuration data. +2. Include plugin database tables in your normal backup and restore process. In particular: + - `Agents_UserAgents` for agents created or managed from the **Agents** page + - `LLM_CustomPrompts` and `LLM_CustomPromptPins` for custom prompt templates and prompt pins +3. For larger deployments, consider backing up indexed vector data separately. -1. Ensure your regular Mattermost backup includes plugin configurations -2. For larger deployments, consider backing up indexed vector data separately +Restoring only plugin configuration isn't sufficient to restore agents managed from the **Agents** page. ### Configuration format -The plugin uses a service-based architecture stored in the Mattermost database at `PluginSettings.Plugins["mattermost-ai"]`: +The plugin uses a service-based architecture: -- **Services** define LLM provider configurations (API keys, models, endpoints) -- **Bots** reference services by ID and define agent personalities and access controls +- `PluginSettings.Plugins["mattermost-ai"]["config"]` stores plugin-wide settings and AI service configurations, including `defaultBotName` +- Agents are stored separately in the `Agents_UserAgents` table -This separation allows multiple bots to share the same LLM service configuration. +This separation allows multiple agents to share the same LLM service configuration while keeping agent lifecycle and access data out of `config.bots`. **Configuration structure:** ```json @@ -310,22 +467,14 @@ This separation allows multiple bots to share the same LLM service configuration "defaultModel": "gpt-4o" } ], - "bots": [ - { - "id": "bot-001", - "name": "ai", - "displayName": "AI Assistant", - "serviceID": "550e8400-e29b-41d4-a716-446655440000", - "customInstructions": "You are a helpful assistant." - } - ] + "defaultBotName": "ai" } } ``` -**Supported service types:** `openai`, `anthropic`, `azure`, `openaicompatible`, `asage`, `cohere`, `mistral` +**Supported service types:** `openai`, `anthropic`, `azure`, `openaicompatible`, `asage`, `cohere`, `mistral`, `scale` -**Legacy format:** Older configurations with embedded service objects within bots are automatically migrated to the current format on plugin startup. +**Legacy format:** Older configurations that stored bots in `config.bots`, or embedded service objects within bots, are migrated on plugin startup. After legacy bot migration completes, stored `config.bots` entries are removed to avoid duplicate bot registration. ## Troubleshooting @@ -338,69 +487,83 @@ Enhanced logging can help diagnose issues: 3. Enable debug logging in the plugin configuration for additional diagnostic information. 4. For production environments, disable debug logging and LLM Trace after troubleshooting to reduce log volume. -## Integrations +### Tool execution failures -Currently integrations are limited to direct messages between users and the agents. The integrations won't operate from within public, private, or group message channels. +When a tool call fails, the agent does not always stop immediately. It may continue with a follow-up model turn so it can recover, explain the failure, or answer without that tool. -### Built-in tool integrations +To avoid endless retries, the plugin enforces a limit of **three consecutive failed tool attempts**. After that, no further tool calls are made for that sequence; the model is instructed to describe the latest error and ask the user for guidance or any missing information such as permissions, identifiers, or configuration details. -#### Server Search +When users report repeated tool failures, use **LLM Trace** and debug logging to inspect tool errors and upstream responses. Also verify integration configuration such as API keys, endpoints, MCP connectivity, and third-party authorization, and confirm the user can access the underlying Mattermost resources the tool targets. -- **Function**: Semantic search across Mattermost content. -- **Requirements**: Embedding search must be configured and enabled. -- **Security**: Respects user permissions - users only see content they have access to. +## Integrations -#### User Lookup +Integrations are available in direct messages by default. If you enable the experimental **Enable Channel Mention Tool Calling** setting, @mentioning an agent in a public channel can also allow tool calling there. Native provider web search in public and private channels is controlled separately by **Allow native web search in channels**. -- **Function**: Look up Mattermost user information by username -- **Data Available**: Username, full name, email, nickname, position, locale, timezone, last activity, status -- **Permissions**: Requires `VIEW_MEMBERS` permission +## Model Context Protocol (MCP) Integration -#### Jira Integration +The Model Context Protocol (MCP) integration lets Agents use tools exposed by MCP servers, including the embedded Mattermost tools and optional remote servers. -- **Function**: Fetch issues from public Jira instances -- **Requirements**: No additional configuration needed -- **Usage**: Provide Jira instance URL and issue keys -- **Data Retrieved**: Issue summary, description, status, assignee, comments, metadata +The MCP client and the embedded Mattermost MCP server are always enabled. Admins manage remote MCP servers, connection timeout, and per-tool enabled state and approval policies from the MCP UI in the System Console. Agent-level MCP access is configured separately on each agent's **MCPs** tab. -#### GitHub Integration +### Configuration -- **Function**: Fetch GitHub issues and pull requests -- **Requirements**: Mattermost GitHub plugin must be installed and running -- **Authentication**: Users must be logged into GitHub through the Mattermost GitHub plugin -- **Access**: Works with both public and private repositories (based on user permissions) -- **Data Retrieved**: Issue/PR title, number, state, submitter, body content +1. Navigate to **System Console > Plugins > Agents > Model Context Protocol (MCP)**. +2. Use the **Configuration** tab for: -**Security Note**: All tool integrations are restricted to direct messages to maintain security boundaries and require explicit user approval before execution. + - **Enable Mattermost MCP Server (HTTP)**: Optional HTTP endpoint for external MCP clients. See [Mattermost MCP Server](#mattermost-mcp-server). + - **Connection Idle Timeout (minutes)**: Timeout for inactive user MCP connections (default: 30 minutes). + - Remote MCP servers, including URL, custom headers, OAuth client settings, and per-server enablement. -## Model Context Protocol (MCP) Integration +3. Use the **Tools** tab to review discovered tools and set each tool's enabled state and approval policy. +4. When creating or editing an agent on the **Agents** page, use the **MCPs** tab to choose whether that agent can use all MCP tools automatically or only a selected set of tools. -The Model Context Protocol (MCP) integration allows Agents to connect to external tools and services through standardized MCP servers. This feature enables expanding AI capabilities with custom integrations. +The **Tools** tab refreshes automatically after the current user connects or disconnects an OAuth-backed MCP server. Because MCP OAuth connections are per-user, this live refresh applies only to the user who completed the connect or disconnect action. -### Configuration +You can't disable MCP entirely from the System Console. To limit access, disable individual tools or change their policy in the **Tools** tab. -1. Navigate to **System Console > Plugins > Agents > MCP Servers**. -2. Enable MCP integration by setting **Enable MCP** to **True**. -3. Configure connection settings: - - - **Idle Timeout**: Set timeout in minutes for inactive client connections (default: 30 minutes) ### Add MCP servers -1. Select **Add MCP Server** to configure a new server. +1. On the **Configuration** tab, select **Add Remote MCP Server** to configure a new server. 2. Configure server settings: - **Server URL**: The endpoint URL for your MCP server. - **Custom Headers**: Additional headers required by your MCP server (optional). - **Server Name**: Descriptive name for the server (auto-generated if not provided). -4. Select **Save** to add the server. +3. Select **Save** to add the server. + +### Configure OAuth-backed servers for agents + +When you create or edit an agent from the **Agents** page, the **MCPs** tab in the full-page agent editor lists the MCP servers available to that agent. If an OAuth-backed server is not connected for your account yet, the row shows a **Connect** button so you can complete the provider sign-in flow without leaving the editor. The MCPs tab refreshes automatically after you connect or disconnect, so you don't need to reopen it to see updated server status. + +If a disconnected OAuth-backed server currently exposes no tools, you can still toggle that server on while configuring the agent. Saving the agent in this state grants the agent access to every tool that server exposes after a user connects to that provider. + +The **Automatically enable all MCP tools** option remains the broadest setting. When enabled, the agent can use every currently available MCP tool as well as MCP tools added later. + +Enabling a server or tool for an agent controls what the agent is allowed to use, but it does not bypass tool approval policies. Tool execution still follows the policy configured in the **Tools** tab and each user's Mattermost and provider permissions. ### Management - **Connection Management**: The system automatically manages user connections to MCP servers - **Idle Cleanup**: Inactive client connections are automatically closed after the configured timeout - **Per-User Connections**: Each user gets their own connection to MCP servers for security and isolation +- **Tool Policies**: Use the **Tools** tab to allow, require approval for, or disable individual tools +- **Agent Scoping**: The RHS **Tools** popover only shows MCP providers allowed for the selected agent. Tool use is still subject to admin tool policies and the user's Mattermost permissions + +### OAuth-backed MCP servers + +Some MCP servers require OAuth per Mattermost user. For those servers, the plugin exposes `needsOAuth` and `authURL` to the Agents webapp so the UI can show when authorization is required and where to begin the flow. The webapp starts OAuth through the plugin route `GET /plugins/mattermost-ai/mcp/oauth//start` and can clear the current user's stored token with `DELETE /plugins/mattermost-ai/mcp/oauth/`. + +**Agents panel (web and desktop):** In the Agents right-hand sidebar, start a new chat and open **Tools**. OAuth-backed servers show **Connect** when the signed-in user is not authenticated, and **Disconnect** when an OAuth session applies. + +**System Console (admin tool configuration):** On **System Console > Plugins > Agents > MCP Servers**, expanding an OAuth-backed server shows that you must authenticate to fetch that server's tool list and configure per-tool approval policies. That sign-in only applies to your administrator account. Each end user must authenticate separately, even after an admin has connected in the System Console. + +**Conversations:** The plugin no longer posts ephemeral in-channel or in-thread messages to prompt MCP OAuth. Users should use the Agents webapp **Tools** menu to view connection state and run **Connect** or **Disconnect**. + +**Mobile and other clients:** MCP OAuth is not initiated from the mobile app or other clients that do not use the Agents webapp. Users need Mattermost web or desktop to connect OAuth-backed MCP servers. + +**Custom MCP OAuth setups:** If the OAuth start URL includes a `resource_metadata` query parameter, it is accepted only when its origin matches the origin of the configured MCP server **Server URL**. This prevents cross-origin metadata injection during discovery. ### Atlassian MCP server authorization @@ -428,11 +591,13 @@ After adding the domain, wait 1-2 minutes for changes to propagate before users For more information, see [Atlassian's documentation on MCP server settings](https://support.atlassian.com/security-and-access-policies/docs/control-atlassian-rovo-mcp-server-settings/). -> **Note:** The plugin currently doesn't render Markdown links (e.g., JIRA ticket links) in bot responses. URLs are displayed in plain text rather than as clickable Markdown-rendered links. This is not a bug but intended security behavior to prevent potential data exfiltration through links. While this limitation exists, improvements to link handling are being considered for future development. +> **Note:** By default, the plugin doesn't render AI-generated Markdown links (for example, JIRA ticket links) as clickable links. URLs are displayed in plain text to reduce potential phishing and data exfiltration risk. If an admin enables **Render AI-generated links** (`allowUnsafeLinks`), AI-generated links may become clickable; enable this only with appropriate trust boundaries and security mitigations in place. ## Mattermost MCP Server -The Mattermost MCP Server enables AI agents and external applications to interact with your Mattermost instance through the Model Context Protocol (MCP). This is a standardized protocol that allows AI assistants to read messages, search content, create posts, and manage channels and teams programmatically. +The Mattermost MCP Server enables AI agents and external applications to interact with your Mattermost instance through the Model Context Protocol (MCP). This is a standardized protocol that allows AI assistants to read messages, search content, create posts, and manage channels and teams programmatically. + +**Standalone MCP server (separate process / stdio):** Running the standalone `mattermost-mcp-server` binary outside the Mattermost server is for **development and local use only** and is **not** intended for production. Production deployments should rely on the embedded Mattermost MCP server and the supported configuration in this plugin (System Console, HTTP endpoint for external clients, and agent MCP settings below). ### Overview @@ -471,21 +636,17 @@ The MCP server provides the following tools to AI agents and external clients: ### Deployment -![MCP Server Configuration](/agents/docs/img/system-console-mcp.png) - #### For AI Agents -To set up an embedded MCP server providing Mattermost AI agents with direct access to Mattermost functionality: +The embedded Mattermost MCP server is available automatically to configured AI agents. No System Console switch is required to enable embedded MCP for in-product agents. -1. Go to **System Console > Plugins > Agents > MCP Servers**. -2. Set **Enable Embedded Server** to **True**. -3. When enabled, all configured agents can access Mattermost tools. +Use **System Console > Plugins > Agents > Model Context Protocol (MCP)** to configure remote MCP servers, the idle timeout, the optional HTTP endpoint for external clients, and per-tool enablement and approval policies. Then use each agent's **MCPs** tab on the **Agents** page to either automatically enable all MCP tools or restrict that agent to specific tools. -Agents will automatically use these tools when appropriate to complete user requests. +Configured agents can use these tools subject to their own MCP settings, admin tool policies, user permissions, and any required approval flow. #### For External Clients -You can enable external MCP clients, such as Claude web, Claude Code, or other MCP-compatible applications, to interact with your Mattermost instance. +You can enable external MCP clients, such as Claude web, Claude Code, or other MCP-compatible applications, to interact with your Mattermost instance. This HTTP server is separate from the always-on embedded MCP server used by Mattermost Agents. **Requirements:** - Mattermost Server v11.2 or later @@ -495,7 +656,7 @@ You can enable external MCP clients, such as Claude web, Claude Code, or other M To enable an external MCP client: -1. Go to **System Console > Plugins > Agents > MCP Servers** +1. Go to **System Console > Plugins > Agents > Model Context Protocol (MCP)** 2. Set **Enable Mattermost MCP Server (HTTP)** to **True**. The MCP server will be available at: `https://your-mattermost-server/plugins/mattermost-ai/mcp-server/mcp` diff --git a/source/_generated/agents/docs/user_guide.md b/source/_generated/agents/docs/user_guide.md index 0d061fda5a9..d6323d7b159 100644 --- a/source/_generated/agents/docs/user_guide.md +++ b/source/_generated/agents/docs/user_guide.md @@ -10,12 +10,16 @@ You can access AI features in Mattermost in the following ways: ### Web and desktop -Access AI features through the right pane in one of the following ways: +Access AI features in one of the following ways: - Select the **Agents** icon in the apps sidebar. - @mention an AI bot in any channel where you have access (such as `@copilot`). +- Open the **AI Actions** menu in the message composer to insert saved **Custom prompts** templates or open **Manage prompts**. - Use the **AI Actions** menu by hovering over the first message in any conversation thread (see [license requirements](https://docs.mattermost.com/administration-guide/configure/agents-admin-guide.html#license-requirements)) - Use the **Ask AI** option in channels with unread messages (see [license requirements](https://docs.mattermost.com/administration-guide/configure/agents-admin-guide.html#license-requirements)) +- Use **Ask Agents about this channel** in a channel header to summarize recent activity, focus on a date range, or ask a question about the current channel. See [Channel Summaries](features/channel_summaries.md). + +![AI Actions menu in the message composer, including the Custom prompts entry.](img/ai-actions-menu-composer.png) ### Mobile @@ -27,29 +31,77 @@ Start or open a direct message with the Agent bot. If your system admin has conf You can have conversations with Agents in several ways: -**Agents pane**: Use the Agents right-hand pane for a streamlined experience. Begin with suggested prompts, or engage in a private thread with an Agent for a tailored experience. If you have follow-up questions or need further insights, simply ask. You can also attach files for AI analysis or reference. +**Agents pane**: Use the Agents right-hand pane for a streamlined experience. Begin with suggested prompts or pinned custom prompt buttons, or engage in a private thread with an Agent for a tailored experience. If you have follow-up questions or need further insights, simply ask. You can also attach files for AI analysis or reference. **Direct messages**: Start a direct message with an Agent bot to have a private conversation. Chat privately with an Agent in direct message threads like you would any other Mattermost user. -**Channel mentions**: [@mention](https://docs.mattermost.com/collaborate/mention-people.html) Agent bots by their username, such as `@copilot`, in any thread to bring Agents capabilities to your conversation. The bot responds in a thread to keep channels organized, and other team members can view and contribute to the conversation. An Agent can help extract information quickly or transform discussions into charts, resources, documentation, and more, and can find action items and open questions in new messages. +**Channel mentions**: [@mention](https://docs.mattermost.com/collaborate/mention-people.html) Agent bots by their username, such as `@copilot`, in any thread to bring Agents capabilities to your conversation. The bot responds in a thread to keep channels organized, and other team members can view and contribute to the conversation. An Agent can help extract information quickly or transform discussions into charts, resources, documentation, and more, and can find action items and open questions in new messages. When you @mention an Agent in a thread, it uses earlier thread context up to that mention, including earlier posts in the thread. Later replies posted after that mention, and temporary placeholder bot posts, aren't included in that request. + +When you attach files in the Agents pane, direct messages, or channel @mentions, Agents can use them as conversation context. Images are included only when vision is enabled for the bot. Other files contribute text only when Mattermost can read text from them, such as plain-text files or files with extracted text. Very large attachment text may be shortened, and if one attachment can't be read, that attachment is skipped while the conversation continues. + +> **Note:** Whether AI-generated links are clickable depends on your system admin configuration. Treat links in AI responses with caution and verify destinations before opening them. ### Select a bot If multiple Agent bots are configured for your Mattermost workspace, select your preferred bot in the Agents pane or @mention specific bots by name in channels. -### Approve tools +### Use custom prompt templates + +Custom prompts are saved prompt templates that you can reuse from the message composer or from pinned buttons in the Agents pane. + +To manage custom prompts: + +1. Open the message composer in any channel or direct message. +2. Select **AI Actions**. +3. Open **Custom prompts**, then select **Manage prompts**. +4. Select **Create new** to open the prompt editor and add a prompt with an **Action Title**, optional description, and template. +5. Choose **Public** to share the prompt with other users, or **Private** to keep it visible only to you. +6. Pin or unpin prompts directly from the prompt list. Pinned prompts appear as shortcuts in the Agents pane. + +The **All Prompts** tab shows prompts you created plus shared prompts from other users. The **Your Prompts** tab shows only prompts you created. Selecting a prompt from either list opens a dedicated prompt view inside the modal, with a back arrow to return to the list and the prompt name as the title. Shared prompts from other users open read-only. Only the prompt creator can edit or delete a prompt. Prompt titles can be up to 64 characters, and every prompt requires a template. + +When you select a saved prompt from **Custom prompts**, Mattermost renders the template with the current context and inserts the result into your draft. If you use this menu outside a bot direct message, Mattermost adds the currently selected bot mention before the rendered text. Pinned prompts in the Agents pane render the current saved template and send it immediately as a message. + +Custom prompt templates support the following variables: + +| Variable | Inserts | +|----------|---------| +| `{{.Username}}` | Your Mattermost username | +| `{{.FirstName}}` | Your first name | +| `{{.LastName}}` | Your last name | +| `{{.Channel}}` | The current channel display name | +| `{{.ChannelName}}` | The current channel name | +| `{{.Team}}` | The current team display name | +| `{{.TeamName}}` | The current team name | +| `{{.Time}}` | The current UTC time | +| `{{.BotName}}` | The selected agent display name, when available | + +If a value isn't available in the current context, the rendered prompt leaves it blank. + +### Use tools + +When Agents use external tools or integrations, Mattermost may prompt you to review tool usage based on the tool approval policy configured by your system admin. When review is required, only the person who requested the Agent interaction can accept or reject pending tools. For those pending tools, you'll see a card showing the tool name and description, arguments being passed to the tool, and **Accept** and **Reject** options. If multiple tools are waiting for a decision, Mattermost may also show **Accept all** and **Reject all** controls. + +By default, tool calls are available in direct messages. If your system admin enables the experimental **Enable Channel Mention Tool Calling** setting, some tools can also run in channels. Depending on the configured tool policy, each tool call may require approval before execution or run automatically. A single Agent response can include both auto-approved tools and tools still waiting for approval. In that case, the auto-approved badge applies only to the individual tool that ran automatically, while pending tools continue to show **Accept** and **Reject** options. Tool results are shown after execution, and if a result needs a visibility decision, you'll see **Share** and **Keep private** options. + +Only the person who started the conversation can approve or reject tool calls. In direct messages with an agent, approved tool results are shared automatically because only you can view that conversation. + +In channels, tool approval can be a two-step process. After you approve a tool call and it runs, Mattermost can prompt you again to decide whether the tool arguments and results should be shared with the channel or kept private. If you choose **Keep Private**, other channel members don't see that tool data, and the channel-visible follow-up response is generated without the private content. -When Agents use external tools or integrations, you may be prompted to approve tool usage for security. When a tool is called, you'll see a card showing the tool name and description, arguments being passed to the tool, and **Approve/Reject** options. +If a tool execution fails, the Agent can continue with a follow-up response instead of stopping immediately. After three consecutive failed tool executions, the Agent stops calling further tools and is instructed to explain the latest error and ask you for guidance or any missing information. A successful tool execution resets that count. -For security, tool calls are only available in direct messages and each tool call requires explicit approval before execution. You can review tool arguments before approving, and tool results are shown after successful execution. +On web and desktop, start a new chat in the Agents right-hand pane and open the **Tools** menu in the header. The menu lists configured tool providers. For MCP servers that use OAuth, you'll see **Connect** when you're not authenticated and **Disconnect** when an OAuth session applies. You can turn individual providers on or off from this menu, and your choices are saved as your personal preferences. Mattermost doesn't send OAuth connection prompts as ephemeral posts in the conversation; use the **Tools** menu to check connection state and complete **Connect** or **Disconnect** flows. -Available tools in direct messages include: +> **Note:** The Mattermost mobile apps don't currently support starting MCP OAuth connections from the Agents experience. Use web or desktop to connect OAuth-backed MCP providers. -- Server search (semantic search across your Mattermost instance) -- User lookup (find information about Mattermost users) -- GitHub integration (the ability to fetch GitHub issues and pull requests requires the [GitHub plugin](https://docs.mattermost.com/integrate/github.html)) -- [Jira integration](https://docs.mattermost.com/integrate/jira.html) (retrieve Jira issues from public instances) -- MCP tools (external tools provided by configured MCP servers if enabled). Tool availability depends on your user permissions and system configuration. +Depending on your workspace configuration, available tools in direct messages, and in channels when enabled by your system admin, can include: + +- Mattermost MCP tools, including tools to search posts and find users in Mattermost, when your system admin has enabled the Mattermost MCP server for Agents +- MCP tools provided by other configured MCP servers, if enabled + +Tool availability depends on your user permissions, provider connection status, and workspace configuration. + +Some MCP providers require each user to connect their own account before those tools become available. When that applies, open the **Tools** menu in the Agents pane or RHS, select **Connect** for the provider, and wait for the list to refresh with the newly available tools. ## Analyze threads and channels @@ -77,7 +129,9 @@ To summarize unread Mattermost channels: 2. Select **Ask AI**. 3. Select **Summarize new messages**. -The channel summary is generated in the Agents pane, and only you can view the summary. Channel summaries include citation links that reference specific messages from the channel. Select a citation link to open a popover preview of the referenced message without navigating away from the channel. +The channel summary is generated in the Agents pane, and only you can view the summary. + +For more flexible channel analysis options, including **Ask Agents about this channel**, prompts, and date ranges, see [Channel Summaries](features/channel_summaries.md). ## Search with AI @@ -91,7 +145,9 @@ Contact your system admin if this feature isn't available for your Mattermost in ## Analyze images -For AI models with vision capabilities, attach an image file to your message when chatting with an Agent to ask questions about the image or request analysis. The Agent responds based on the visual content. +For AI models with vision capabilities, attach an image file to your message when chatting with an Agent or @mentioning an Agent in a channel to ask questions about the image or request analysis. The Agent responds based on the visual content. + +In channel threads, a later @mention can also include image attachments from earlier posts in the same thread when those posts are part of the thread context. Your system admin must enable vision capabilities for your bot, and the underlying AI model must support vision features. @@ -107,3 +163,24 @@ To summarize a Mattermost call recording: The meeting summary is generated and shared as a direct message with the person who requested the meeting summary. Both call recordings and recorded meeting summarization require a license. See [license requirements](https://docs.mattermost.com/administration-guide/configure/agents-admin-guide.html#license-requirements) for details. Contact your system admin if these features aren't available for your Mattermost instance. + + +## Summarize Zoom meetings in Mattermost + +The Zoom plugin must be [enabled and configured](https://docs.mattermost.com/integrate/zoom.html) by a Mattermost system admin and Zoom cloud recordings and transcripts must be enabled before you can summarize Zoom meetings. + +If the Zoom plugin is enabled and configured, subscribe a Mattermost channel to a Zoom meeting (`/zoom subscription add [meeting ID]`) and record the meeting. Once the recording and transcription are available, they are automatically shared back to the channel. + +Use Mattermost to turn Zoom meeting recordings into actionable AI-generated summaries with any model of your choosing, including your own. By summarizing your Zoom meeting recordings in Mattermost, you can easily share the insights with your team and the broader organization, enhancing communication and productivity without sacrificing data privacy and control. + +To summarize a Zoom meeting in Mattermost: + +1. Subscribe a Mattermost channel to a recurring Zoom meeting with `/zoom subscription add [meeting ID]` or start a meeting using the Zoom button in the Mattermost right-hand sidebar (RHS). +2. Record the Zoom meeting. +3. Once the meeting ends and the transcript file is posted to Mattermost, select the **Create meeting summary** option located directly above the file. + +![Select the Create meeting summary option to summarize your Zoom meeting in Mattermost.](img/create-meeting-summary-zoom.png) + +4. The meeting summary is generated and shared as a direct message with the person who requested the meeting summary. + +![Easily share the updates from your Zoom meetings with your team and broader organization by turning recordings into detailed summaries at the click of a button.](img/copilot-Zoom-Meeting-Summary.png) diff --git a/source/administration-guide/compliance-with-mattermost.rst b/source/administration-guide/compliance-with-mattermost.rst index 203091199cd..10eff5ddea8 100644 --- a/source/administration-guide/compliance-with-mattermost.rst +++ b/source/administration-guide/compliance-with-mattermost.rst @@ -15,6 +15,7 @@ Mattermost is purpose-built to help enterprises keep sensitive data safe and com Export channel data Legal Hold JSON audit log schema + Post delivery audit logging * :doc:`Compliance exports ` - Export compliance reports to third-party systems to archive history. * :doc:`Compliance monitoring ` - Enable oversight and prevent unauthorized queries with compliance exports. @@ -22,4 +23,5 @@ Mattermost is purpose-built to help enterprises keep sensitive data safe and com * :doc:`Data retention ` - Control how long data is stored in Mattermost with global and custom retention policies to meet data retention compliance requirements. * :doc:`Export channel data ` - Migrate data between systems and back data up for operational continuity. * :doc:`Legal Hold ` - Preserve relevant Mattermost information when litigation is anticipated. -* :doc:`JSON audit log schema ` - Learn how to configure Mattermost audit logging using a JSON object. \ No newline at end of file +* :doc:`JSON audit log schema ` - Learn how to configure Mattermost audit logging using a JSON object. +* :doc:`Post delivery audit logging ` - Record an audit log entry each time a message is delivered to a user, to establish which users a given message reached. \ No newline at end of file diff --git a/source/administration-guide/comply/embedded-json-audit-log-schema.rst b/source/administration-guide/comply/embedded-json-audit-log-schema.rst index 75a0d4d5675..80dbca3cf75 100644 --- a/source/administration-guide/comply/embedded-json-audit-log-schema.rst +++ b/source/administration-guide/comply/embedded-json-audit-log-schema.rst @@ -356,6 +356,19 @@ Posts & Content Events .. note:: From Mattermost v11.5.0, audit log entries for posts and content access events include a ``non_channel_member_access`` field in the ``meta`` object. When a user accesses posts or content in a channel they are not a member of, this field is set to ``true``. Admins can use this indicator to identify and review unauthorized or unexpected content access in their audit logs. +Post Delivery Events +~~~~~~~~~~~~~~~~~~~~ + +From Mattermost v12.0, ``postDelivered`` is written at the ``audit-delivery`` log level rather than alongside the other audit log levels, and only when :doc:`post delivery audit logging ` is enabled. See that page for the record format, the payload fields, and the full set of delivery mechanisms. + ++----------------------------------+-------------------------------------------------------------------+ +| **Event Name** | **Description** | ++==================================+===================================================================+ +| ``postDelivered`` | Delivering post content to a user or integration | ++----------------------------------+-------------------------------------------------------------------+ +| ``updateDeliveryTrackingConfig`` | Updating the post delivery audit logging configuration | ++----------------------------------+-------------------------------------------------------------------+ + Authentication and Security Events ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/administration-guide/comply/post-delivery-audit-logging.rst b/source/administration-guide/comply/post-delivery-audit-logging.rst new file mode 100644 index 00000000000..8d5a9ad7711 --- /dev/null +++ b/source/administration-guide/comply/post-delivery-audit-logging.rst @@ -0,0 +1,211 @@ +Post delivery audit logging +============================ + +.. include:: ../../_static/badges/entry-adv.rst + :start-after: :nosearch: + +From Mattermost v12.0, Mattermost can record an audit log entry each time a message's content is delivered to a user or to an integration. These records let you establish which users a given message was delivered to, and by what means. + +.. note:: + + Post delivery audit logging is currently in :ref:`Beta `. + +Delivery records are ordinary audit log records, written through the existing audit logging pipeline to whichever audit log targets you've configured. Mattermost never reads them back. They're not shown anywhere in the Mattermost interface, they're not included in any report, and there's no REST API for retrieving them. Consuming delivery records is your responsibility, using whatever tooling already ingests your Mattermost audit logs. Retention is whatever your audit log pipeline provides. + +Before you begin +---------------- + +Post delivery audit logging requires all of the following: + +- A Mattermost Enterprise Advanced license. +- The `feature flag `_ ``MM_FEATUREFLAGS_POSTDELIVERYTRACKING``, which is disabled by default. **Restart the server after enabling the feature flag**, because the delivery tracking API endpoints are registered only at startup. +- An audit log target that consumes the ``audit-delivery`` log level. + +.. important:: + + Enabling post delivery audit logging on its own produces no output. Delivery records are discarded until an audit log target consumes the ``audit-delivery`` log level, and log volume increases substantially once one does. Configure the target before you enable the feature. + +Configure an audit log target +----------------------------- + +Delivery records are written at the ``audit-delivery`` log level, ID ``104``. Unlike the other :ref:`audit log levels `, ``audit-delivery`` isn't written by the built-in audit log file target, so enabling ``ExperimentalAuditSettings.FileEnabled`` doesn't capture delivery records. Add a target that consumes level ``104`` to ``ExperimentalAuditSettings.AdvancedLoggingJSON`` instead. See :ref:`advanced logging ` for the available target types and options. + +We recommend a dedicated target, so that the volume of delivery records doesn't overwhelm your other audit records. The example below writes delivery records to their own file, rotated at 100 MB, with up to 10,000 records buffered in memory while writing: + +.. code-block:: JSON + + { + "post-delivery-audit": { + "type": "file", + "format": "json", + "levels": [ + { "id": 104, "name": "audit-delivery" } + ], + "options": { + "filename": "./logs/post-delivery-audit.log", + "max_size": 100, + "max_age": 0, + "max_backups": 0, + "compress": true + }, + "maxqueuesize": 10000 + } + } + +If post delivery audit logging is enabled and no audit log target consumes the ``audit-delivery`` level, the configuration remains valid, delivery records are discarded, and Mattermost logs the following warning at startup and whenever the configuration changes: + +.. code-block:: text + + DeliveryTrackingSettings.Enable is enabled but no configured audit log target consumes the audit-delivery level; post delivery audit records will be discarded. Add a target for the level via ExperimentalAuditSettings.AdvancedLoggingJSON. + +Enable post delivery audit logging +---------------------------------- + +In the System Console, enable post delivery audit logging and choose the channels that deliveries are recorded in by going to **Site Configuration > Data Spillage Handling > Post Delivery Audit Logging**. See :ref:`administration-guide/manage/admin/content-flagging:post delivery audit logging` for the steps, and :ref:`administration-guide/configure/site-configuration-settings:content flagging` for the corresponding ``config.json`` settings and environment variables. + +Record format +------------- + +Each delivery is recorded as a ``postDelivered`` audit log record. The ``status`` of the record is always ``success``. + +**The recipient of the message is the actor of the record**, in ``actor.user_id``. There's no separate recipient field. This lets you group records by actor to answer "what was delivered to this user". Deliveries to a plugin or to an outgoing webhook have no human recipient, so ``actor.user_id`` is empty and ``meta.plugin_id`` or ``meta.webhook_id`` identifies the integration instead. + +The ``meta`` object identifies what was delivered and how. Unlike audit records emitted from a REST API request, delivery records carry no ``api_path`` or ``cluster_id`` in ``meta``. + +A message delivered to a user through the Mattermost REST API: + +.. code-block:: json + + { + "timestamp": "2026-08-12 14:03:11.482 Z", + "event_name": "postDelivered", + "status": "success", + "actor": { + "user_id": "hx4k9m2qzbfytr7wn6cbd3jvse", + "session_id": "", + "client": "", + "ip_address": "" + }, + "meta": { + "post_id": "xpw97hf6kfncirzhqisb5sym7e", + "channel_id": "pfis7ycuy78o7m3zebajmxqeuo", + "mechanism": "product" + }, + "error": {} + } + +The same message delivered to a plugin, with no human recipient: + +.. code-block:: json + + { + "timestamp": "2026-08-12 14:03:11.509 Z", + "event_name": "postDelivered", + "status": "success", + "actor": { + "user_id": "", + "session_id": "", + "client": "", + "ip_address": "" + }, + "meta": { + "post_id": "xpw97hf6kfncirzhqisb5sym7e", + "channel_id": "pfis7ycuy78o7m3zebajmxqeuo", + "mechanism": "plugin", + "plugin_id": "com.mattermost.example-plugin" + }, + "error": {} + } + +See the :doc:`audit log JSON schema ` for the fields common to every Mattermost audit log record. + +Payload fields +-------------- + +The ``meta`` object of a ``postDelivered`` record contains the following fields. The recipient isn't in ``meta`` — the recipient is the actor of the record, in ``actor.user_id``. + ++--------------------+---------------+-----------------------------------------------------------------------+ +| **Field name** | **Data type** | **Description** | ++====================+===============+=======================================================================+ +| post_id | string | Always present. The unique identifier of the message whose content | +| | | was delivered. | ++--------------------+---------------+-----------------------------------------------------------------------+ +| channel_id | string | Always present. The unique identifier of the channel that the message | +| | | belongs to. | ++--------------------+---------------+-----------------------------------------------------------------------+ +| mechanism | string | Always present. How the message content reached the recipient. See | +| | | `delivery mechanisms <#delivery-mechanisms>`__ for the possible | +| | | values. | ++--------------------+---------------+-----------------------------------------------------------------------+ +| plugin_id | string | Present for ``plugin`` deliveries only. The plugin that the message | +| | | content was passed to. | ++--------------------+---------------+-----------------------------------------------------------------------+ +| webhook_id | string | Present for ``outgoing_webhook`` deliveries only. The outgoing | +| | | webhook that the message content was sent to. | ++--------------------+---------------+-----------------------------------------------------------------------+ +| via_post_id | string | Present for ``permalink_preview`` deliveries only. The message that | +| | | embedded the permalink preview. | ++--------------------+---------------+-----------------------------------------------------------------------+ +| via_channel_id | string | Present for ``permalink_preview`` deliveries only. The channel | +| | | containing the message that embedded the permalink preview. | ++--------------------+---------------+-----------------------------------------------------------------------+ + +Delivery mechanisms +------------------- + +The ``mechanism`` field records how the message content reached the recipient. It's always one of the following seven values: + ++-----------------------+--------------------------------------------------------------------------------+ +| **Value** | **Delivery** | ++=======================+================================================================================+ +| ``product`` | Any read of message content through the Mattermost REST API. This covers | +| | channel loads, thread and reply views, search results, direct fetches of a | +| | message by ID, pinned messages, saved messages, and message edit history. | ++-----------------------+--------------------------------------------------------------------------------+ +| ``post_broadcast`` | A new or edited message pushed over WebSocket to connected channel members. | ++-----------------------+--------------------------------------------------------------------------------+ +| ``permalink_preview`` | A message rendered as a permalink preview inside another message. | ++-----------------------+--------------------------------------------------------------------------------+ +| ``email`` | Message content included in a notification email. | ++-----------------------+--------------------------------------------------------------------------------+ +| ``push`` | Message content included in a push notification payload, and the | +| | acknowledgement fetch that retrieves content for an ID-only push notification. | ++-----------------------+--------------------------------------------------------------------------------+ +| ``outgoing_webhook`` | Message content sent to an outgoing webhook. | ++-----------------------+--------------------------------------------------------------------------------+ +| ``plugin`` | A message passed to a plugin's ``MessageWillBePosted`` or | +| | ``MessageWillBeUpdated`` hook, or read through the plugin API. | ++-----------------------+--------------------------------------------------------------------------------+ + +.. note:: + + Channel loads, thread views, search results, and direct message fetches all share the ``product`` value. They aren't reported as separate mechanisms. + +What isn't recorded +------------------- + +The following are never recorded: + +- **The message author**: A user never receives a delivery record for their own message. +- **System messages and ephemeral messages**. +- **Burn-on-read messages**. +- **Direct and group messages**: These channels are never eligible, including when deliveries are recorded in all channels. +- **Generic push notifications**: A push notification that doesn't include message content records nothing. When push notifications are configured to send only IDs, the delivery is recorded when the device fetches the content. +- **Plugins reading from the database**: A plugin that reads messages directly from the database, rather than through the plugin API or a message hook, can't be observed and isn't recorded. + +Messages posted by bots and by outgoing webhooks are recorded like any other message. + +Interpret delivery records +-------------------------- + +Mattermost records one entry for each message delivered to each recipient, with no batching. A channel load that returns 100 messages produces 100 records, and a new message broadcast to 40 connected channel members produces 40 records. + +Delivery records are an append-only event stream, not a deduplicated list of who has seen a message. The same combination of user, message, and mechanism recurs, because every time a user revisits a channel the same page of messages is delivered again. Each record is a genuine delivery with its own timestamp. + +To build a distinct list of the users a message was delivered to, deduplicate on ``actor.user_id``, ``meta.post_id``, and ``meta.mechanism``, and treat the earliest timestamp in each group as the first delivery. + +Keep the following in mind when working with delivery records: + +- **Delivery isn't proof of reading**: A record means Mattermost transmitted the message content to an endpoint the recipient could read it from. It doesn't mean anyone read it. A user with email notifications configured to include message content is recorded as a delivery even if they never opened Mattermost. +- **Records aren't guaranteed to be complete**: Audit logging is asynchronous, so records still queued in memory are lost if the server stops uncleanly. A controlled shutdown flushes the queue. This is existing audit logging behaviour that applies to all audit log levels. +- **Permalink previews follow the previewed message**: Whether a permalink preview delivery is recorded depends on the channel of the message being previewed, not the channel of the message containing the preview. A preview of a message in a recorded channel is recorded even when the preview is rendered in a channel that isn't. Without this, a recorded message could be read by permalinking it into any other channel. Mattermost renders one level of permalink preview, so one level is recorded. diff --git a/source/administration-guide/configure/environment-configuration-settings.rst b/source/administration-guide/configure/environment-configuration-settings.rst index 29e01de9b2c..7df3daa9634 100644 --- a/source/administration-guide/configure/environment-configuration-settings.rst +++ b/source/administration-guide/configure/environment-configuration-settings.rst @@ -3932,6 +3932,7 @@ Output audit logs to multiple targets - See the :doc:`Mattermost logging ` documentation for details on advanced logging configuration. These targets have been chosen as they support the vast majority of log aggregators, and other log analysis tools, without needing additional software installed. - Audit logs are recorded asynchronously to reduce latency to the caller. - Advanced audit logging supports hot-reloading of logger configuration. + - From Mattermost v12.0, the ``audit-delivery`` log level (ID ``104``) isn't written by the built-in audit log file target. To capture :doc:`post delivery audit records `, add a target for the level here. ---- diff --git a/source/administration-guide/configure/site-configuration-settings.rst b/source/administration-guide/configure/site-configuration-settings.rst index 839b5074260..fab8f82a080 100644 --- a/source/administration-guide/configure/site-configuration-settings.rst +++ b/source/administration-guide/configure/site-configuration-settings.rst @@ -2259,6 +2259,84 @@ Team administrators as reviewers | as reviewers. | | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +From Mattermost v12.0, the following settings control post delivery audit logging, which records an audit log entry each time a message is delivered to a user. Delivery records require an audit log target that consumes the ``audit-delivery`` log level. See :doc:`Post delivery audit logging ` for details. + +.. note:: + + Post delivery audit logging is currently in :ref:`Beta `, and requires the `feature flag `_ ``MM_FEATUREFLAGS_POSTDELIVERYTRACKING``. Restart the server after enabling the feature flag. + +.. config:setting:: delivery-tracking-enable + :displayname: Enable post delivery audit logging (Content flagging) + :systemconsole: Site Configuration > Content Flagging + :configjson: .DeliveryTrackingSettings.Enable + :environment: MM_DELIVERYTRACKINGSETTINGS_ENABLE + :description: Record an audit log entry each time a message is delivered to a user. Default is **false**. + + - **true**: An audit log entry is recorded each time a message is delivered to a user. + - **false**: **(Default)** Message deliveries aren't recorded. + +Enable post delivery audit logging +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +| - **true**: An audit log entry is recorded each time | - System Config path: **Site Configuration > Content Flagging** | +| a message is delivered to a user. | - ``config.json`` setting: ``DeliveryTrackingSettings`` > ``Enable`` > ``false`` | +| - **false**: **(Default)** Message deliveries aren't | - Environment variable: ``MM_DELIVERYTRACKINGSETTINGS_ENABLE`` | +| recorded. | | ++-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ + +.. note:: + + Delivery records are written to the audit log only, and aren't surfaced anywhere in the Mattermost interface. They're discarded unless an audit log target consumes the ``audit-delivery`` log level. + +.. config:setting:: delivery-tracking-all-channels + :displayname: Record deliveries in (Content flagging) + :systemconsole: Site Configuration > Content Flagging + :configjson: .DeliveryTrackingSettings.EnableForAllChannels + :environment: MM_DELIVERYTRACKINGSETTINGS_ENABLEFORALLCHANNELS + :description: Record message deliveries in all eligible channels, or only in selected channels. Default is **true**. + + - **true**: **(Default)** Deliveries are recorded in all eligible channels. + - **false**: Deliveries are recorded only in the selected channels. + +Record deliveries in +~~~~~~~~~~~~~~~~~~~~ + ++-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +| - **true**: **(Default)** Deliveries are recorded in | - System Config path: **Site Configuration > Content Flagging** | +| all eligible channels. | - ``config.json`` setting: ``DeliveryTrackingSettings`` > ``EnableForAllChannels`` > ``true`` | +| - **false**: Deliveries are recorded only in the | - Environment variable: ``MM_DELIVERYTRACKINGSETTINGS_ENABLEFORALLCHANNELS`` | +| selected channels. | | ++-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ + +.. note:: + + Recording deliveries in all channels is the most complete option, and also the most expensive. Direct and group messages are never eligible, regardless of this setting. + +.. config:setting:: delivery-tracking-channels + :displayname: Channels to record deliveries in (Content flagging) + :systemconsole: Site Configuration > Content Flagging + :configjson: N/A + :environment: N/A + :description: The channels in which message deliveries are recorded when deliveries aren't recorded in all channels. The list is stored in the database, so there's no ``config.json`` setting and no environment variable. Manage it in the System Console, or through the ``/api/v4/delivery_tracking/config`` API endpoints. + +Channels to record deliveries in +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +| The channels in which message deliveries are | - System Config path: **Site Configuration > Content Flagging** | +| recorded. Applies only when **Record deliveries in** | - ``config.json`` setting: N/A | +| is set to **Selected channels**, in which case at | - Environment variable: N/A | +| least one channel is required. | | +| | | +| Stored in the database, so there's no | | +| ``config.json`` setting and no environment variable. | | +| Manage the list in the System Console, or through the | | +| ``/api/v4/delivery_tracking/config`` API endpoints. | | +| | | +| Direct and group message channels can't be selected. | | ++-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ + ---- File sharing and downloads diff --git a/source/administration-guide/manage/admin/content-flagging.rst b/source/administration-guide/manage/admin/content-flagging.rst index 58738cad245..bc97a3a6e67 100644 --- a/source/administration-guide/manage/admin/content-flagging.rst +++ b/source/administration-guide/manage/admin/content-flagging.rst @@ -59,6 +59,14 @@ Configure - **Require reviewers to add comment**: Set to **True** to require reviewers to add a comment when resolving a quarantine. - **Hide message from channel while it is being reviewed**: Set to **True** to automatically hide quarantined messages from the channel until reviews are complete. If a root post is quarantined, the entire thread is hidden. +4. Under **Post Delivery Audit Logging**, record which users messages are delivered to: + + - **Enable post delivery audit logging**: Set to **True** to record an audit log entry each time a message is delivered to a user. These records are written to the audit log only, and aren't surfaced anywhere in the Mattermost interface. + - **Record deliveries in**: Select **All channels**, or select **Selected channels** to limit recording to specific channels. + - **Channels to record deliveries in**: With **Selected channels** set, select the channels in which deliveries are recorded. + + See :ref:`administration-guide/manage/admin/content-flagging:post delivery audit logging` for details. + .. tip:: We recommend enabling **Hide message from channel while it is being reviewed** and require comments from both reporters and reviewers to maintain transparency, accountability, and an auditable record of actions. @@ -188,6 +196,37 @@ When any step reports **Partial** or **Failed**, the report displays an *incompl The post deletion report is the single source of truth for post-removal auditing. It isn't stored elsewhere in the System Console, so the reviewer thread containing the report should be retained in line with your organization's audit retention policy. +Post delivery audit logging +--------------------------- + +From Mattermost v12.0, Mattermost can record an audit log entry each time a message is delivered to a user, so that you can establish which users a given message was delivered to. Delivery records add storage and processing cost, so enable them only where they're needed. + +.. note:: + + Post delivery audit logging is currently in :ref:`Beta `. + +Delivery records are written to the audit log only. They aren't surfaced anywhere in the Mattermost interface, and they aren't included in any Mattermost report. To use them, ingest them with the same pipeline you use for the rest of your Mattermost audit log. + +To enable post delivery audit logging: + +1. Add an audit log target that consumes the ``audit-delivery`` log level. Delivery records are discarded until a target consumes them, so do this first. See :doc:`Post delivery audit logging `. +2. Go to **System Console > Site Configuration > Data Spillage Handling**, and find **Post Delivery Audit Logging**. +3. Set **Enable post delivery audit logging** to **True**. +4. Set **Record deliveries in**: + + - **All channels**: Deliveries are recorded in every eligible channel. This is the most complete option, and the most expensive. + - **Selected channels**: Deliveries are recorded only in the channels you select. At least one channel is required. + +5. With **Selected channels** set, use **Channels to record deliveries in** to select the channels. Direct and group message channels can't be selected. Recording starts when you save, and applies to messages sent from then on. + +**Enable post delivery audit logging** and **Record deliveries in** can also be configured via the :ref:`config.json file or through environment variables `. + +The list of channels isn't stored in ``config.json``. Mattermost stores it in the database, so manage it either in the System Console or through the ``/api/v4/delivery_tracking/config`` API endpoints. A ``PUT`` request that omits ``ChannelIds`` leaves the stored list unchanged, and an empty array clears it. See the `Mattermost API reference `__. + +.. tip:: + + See :doc:`Post delivery audit logging ` for the format of a delivery record, every delivery mechanism that's recorded, what isn't recorded, and how to interpret the records. + Best practice recommendations ----------------------------- diff --git a/source/administration-guide/manage/logging.rst b/source/administration-guide/manage/logging.rst index 71e657805b6..5d5a04f37f2 100644 --- a/source/administration-guide/manage/logging.rst +++ b/source/administration-guide/manage/logging.rst @@ -38,6 +38,8 @@ System admins can customize the following logging options based on your business - Audit logging configurations reject standard log levels (``debug``, ``info``, ``warn``, ``error``, ``fatal``, ``panic``, etc.) - Configuration validation occurs at startup and when updating settings, preventing invalid log level combinations + From Mattermost v12.0, standard logging configurations also reject the ``audit-delivery`` log level. + Console logs ------------ @@ -212,7 +214,7 @@ Audit logging By default, Mattermost doesn't write audit logs locally to a file on the server, and the ability to enable audit logging in Mattermost is currently in :ref:`Beta `. -You can enable and customize advanced audit logging in Mattermost to record activities and events performed within Mattermost, such as user access to the Mattermost REST API or mmctl. Audit logs are recorded asynchronously to reduce latency to the caller, and are stored separately from general logging. During short spans of inability to write to targets, the audit records buffer in memory with a configurable maximum record cap. Based on typical audit record volumes, it could take many minutes to fill the buffer. After that, the records are dropped, and the record drop event is logged. +You can enable and customize advanced audit logging in Mattermost to record activities and events performed within Mattermost, such as user access to the Mattermost REST API or mmctl. Audit logs are recorded asynchronously to reduce latency to the caller, and are stored separately from general logging. During short spans of inability to write to targets, the audit records buffer in memory with a configurable maximum record cap. Based on typical audit record volumes, it could take many minutes to fill the buffer. After that, the records are dropped, and the record drop event is logged. From Mattermost v12.0, the default maximum number of buffered audit records is 10,000, increased from 1,000. .. note:: @@ -690,6 +692,14 @@ The following log levels support audit logs: +--------+-----------------------+------------------------------------------------------------------------+ | 103 | ``audit-cli`` | CLI operations | +--------+-----------------------+------------------------------------------------------------------------+ +| 104 | ``audit-delivery`` | Deliveries of message content to users and integrations. Available | +| | | from Mattermost v12.0. This log level generates considerably more | +| | | records than any other audit log level. | ++--------+-----------------------+------------------------------------------------------------------------+ + +.. note:: + + The ``audit-delivery`` log level isn't written by the built-in audit log file target, so enabling ``ExperimentalAuditSettings.FileEnabled`` doesn't capture delivery records. To capture them, add a target for the level to ``ExperimentalAuditSettings.AdvancedLoggingJSON``. See :doc:`Post delivery audit logging `. The following log levels support application logs: From 8e91f592ec1735eca0e3ce079a211bb7833bfb83 Mon Sep 17 00:00:00 2001 From: Harshil Sharma Date: Fri, 14 Aug 2026 11:38:06 +0530 Subject: [PATCH 2/6] Revert unrelated agents generated-doc drift source/_generated/agents/docs/{admin_guide,user_guide}.md are rewritten by every local docs build, and the resulting drift was picked up by the previous commit. Restore both files to their state on master; they are unrelated to the post delivery audit logging docs. Co-Authored-By: Claude Opus 5 --- source/_generated/agents/docs/admin_guide.md | 323 +++++-------------- source/_generated/agents/docs/user_guide.md | 105 +----- 2 files changed, 95 insertions(+), 333 deletions(-) diff --git a/source/_generated/agents/docs/admin_guide.md b/source/_generated/agents/docs/admin_guide.md index c63ff04b8c7..b86fc4d5a67 100644 --- a/source/_generated/agents/docs/admin_guide.md +++ b/source/_generated/agents/docs/admin_guide.md @@ -12,7 +12,6 @@ Before installing the Agents plugin, ensure your environment meets these require - PostgreSQL database - For semantic search: PostgreSQL with pgvector extension - Network access to your chosen LLM provider -- If outbound LLM traffic must use an HTTP proxy, set `HTTP_PROXY` and `HTTPS_PROXY` on the Mattermost server process or container environment. - API keys if using a cloud LLM service ### Installation Steps @@ -23,7 +22,7 @@ From Mattermost v10.3, Agents comes installed automatically and ready for you to #### Install latest version -For the most recent features and improvements, you can download and install the latest plugin version from the [GitHub releases page](https://github.com/mattermost/mattermost-plugin-agents/releases). +For the most recent features and improvements, you can download and install the latest plugin version from the [GitHub releases page](https://github.com/mattermost/mattermost-plugin-ai/releases). Install the plugin through the System Console by navigating to **System Console > Plugin Management**, clicking **Upload Plugin**, selecting the downloaded plugin file (.tar.gz), and clicking **Upload**. Enable the plugin after upload completes, then configure plugin settings as detailed in the Configuration section below. @@ -31,9 +30,7 @@ Install the plugin through the System Console by navigating to **System Console ### Access plugin settings -Navigate to **System Console > Plugins > Agents** to configure plugin-wide settings such as AI services, the default bot, web search, embedding search, and MCP settings. - -Create and manage agents from the top-level **Agents** product page. You can also open it from **AI Actions > Manage agents**. The **AI Bots** section in the System Console links to the Agents page instead of hosting the full agent editor. +Navigate to **System Console > Plugins > Agents** to access the configuration interface. ### Enable the plugin @@ -43,21 +40,7 @@ Agents is enabled automatically when using the pre-installed version. If you've If you have an Enterprise, or Enterprise Advanced license, upload it to unlock additional features. If you don't have a license but are running Mattermost Enterprise Edition, an Entry license will be automatically applied for you. -For general settings, you can toggle to enable or disable the plugin system-wide, enable debug logging for troubleshooting (use only when needed), enable token usage logging for tracking LLM interactions, and configure the hostname allowlist for API calls. Outbound LLM provider traffic respects `HTTP_PROXY` and `HTTPS_PROXY` when they are set on the Mattermost server process. - -### AI response link rendering - -Mattermost Agents includes a setting that controls whether AI-generated Markdown links are rendered as clickable links in responses: - -- **System Console label**: **Render AI-generated links** -- **Configuration key**: `allowUnsafeLinks` -- **Default value**: `false` - -When **Render AI-generated links** is set to **False** (default), AI-generated Markdown links are shown as plain text and are not rendered as clickable links. - -When this setting is set to **True**, AI-generated links may be rendered as clickable links. This is a security tradeoff: AI output can include malicious destinations, which can increase phishing and data exfiltration risk. - -Enable this setting only in trusted or otherwise mitigated environments, such as where users are trained to validate links and your organization has endpoint protections and URL controls in place. +For general settings, you can toggle to enable or disable the plugin system-wide, enable debug logging for troubleshooting (use only when needed), enable token usage logging for tracking LLM interactions, and configure the hostname allowlist for API calls. ### Service configuration @@ -68,14 +51,14 @@ Navigate to **System Console > Plugins > Agents** and select **Add a Service**. | Setting | Description | |---------|-------------| | **Name** | Internal name for this service configuration | -| **Type** | LLM provider (OpenAI, Anthropic, AWS Bedrock, Cohere, Mistral, Scale AI, Azure OpenAI, OpenAI-compatible) | +| **Type** | LLM provider (OpenAI, Anthropic, AWS Bedrock, Cohere, Mistral, Azure OpenAI, OpenAI-compatible) | | **API Key** | Your provider's API key (requirements vary by provider) | | **Default Model** | Default model to use for this service | | **Input Token Limit** | Maximum tokens allowed in input | | **Output Token Limit** | Maximum tokens allowed in output | | **Streaming Timeout Seconds** | Timeout in seconds for streaming responses | | **Send User ID** | Whether to send Mattermost user IDs to the LLM provider | -| **Use Responses API** | (OpenAI Compatible and Azure OpenAI only) Use OpenAI's Responses API for native provider tools, reasoning controls, and structured output on those endpoints. OpenAI (direct) always uses the Responses API, so this control isn't shown for that service type. | +| **Use Responses API** | (OpenAI/Compatible only) Enable OpenAI's Responses API for richer tool integration | #### Provider Specific Settings @@ -83,85 +66,47 @@ Each provider has specific configuration requirements: | Provider | Required Settings | Optional Settings | |----------|-------------------|-------------------| -| **OpenAI** | API Key | Organization ID | -| **OpenAI Compatible** | API URL | API Key, Organization ID | +| **OpenAI** | API Key | Organization ID, API URL (for compatible services) | | **Anthropic** | API Key | | | **AWS Bedrock** | AWS Region | API Key (can use IAM role), Access/Secret Keys | | **Cohere** | API Key | | | **Mistral** | API Key | | -| **Scale AI** | API Key, API URL | Account ID (required for ScaleGov) | | **Azure OpenAI** | API Key, API URL | | For AWS Bedrock, authentication can be configured using AWS credentials in the API Key/Secret fields, or by using IAM roles when running Mattermost on AWS infrastructure. **Important for Anthropic Claude models**: Before using Claude models via AWS Bedrock, you must submit a one-time First Time Use (FTU) form in the AWS Bedrock Model Catalog, and attach Bedrock API permissions to your Mattermost servers' IAM role. See the [AWS Bedrock setup guide](https://docs.mattermost.com/agents/docs/aws_bedrock_setup.html) for detailed instructions. -OpenAI services always use the Responses API. OpenAI Compatible and Azure services keep the **Use Responses API** setting so you can disable it for endpoints that still require legacy Chat Completions compatibility. - See the [Provider Guide](https://docs.mattermost.com/agents/docs/providers.html) for detailed provider-specific configuration. ### Agent configuration -Create and manage agents from the **Agents** product page. Open it from the top-level **Agents** product entry or from **AI Actions > Manage agents**. Agents use the service inventory configured in **System Console > Plugins > Agents**, and multiple agents can reuse the same service configuration. See [license requirements](#license-requirements) for details on features that require a license. - -If you can manage an agent, select its row in the Agents list to open the full-page configuration view directly. The overflow menu remains available for **Edit** and **Delete**. Use **Back to agents** to return to the list. - -When you create or edit an agent, use the three tabs in the full-page agent configuration view: - -- **Configuration** for identity, model selection, instructions, and core capabilities -- **Access** for channel, team, and user restrictions, plus delegated agent admins -- **MCPs** for the agent's allowed MCP tools +Create an Agent (Bot) that uses a configured Service. Multiple Agents can use the same Service configuration. See [license requirements](#license-requirements) for details on features that require a license. -If you have unsaved changes and try to leave the agent configuration view by selecting **Back to agents**, **Cancel**, or by pressing Escape, Mattermost shows a **Discard changes?** confirmation with **Discard** and **Keep editing**. - -#### Configuration tab +Navigate to **System Console > Plugins > Agents** and select **Add an Agent**. | Setting | Description | |---------|-------------| | **Display Name** | User-facing name shown in Mattermost | -| **Agent Username** | The Mattermost username for the agent. @mentions use this name. Set it when creating the agent; it can't be changed later. | +| **Agent Username** | The mattermost username for the agent. @ mentions to the agent will use this name | | **Agent Avatar** | Custom image for the agent | | **Service** | Select a configured Service from the dropdown | | **Model** | (Optional) Override the service's default model for this agent | | **Custom Instructions** | Custom instructions that define the agent's personality and capabilities | | **Enable Vision** | Enable Vision to allow the agent to process images. Requires a compatible model and service. | -| **Enable Tools** | Enables tool use for integrations and other tool-based capabilities. Disable this only for models or use cases where tool calling shouldn't be available. Some features won't work without tools. | +| **Enable Tools** | By default some tool use is enabled to allow for features such as integrations with JIRA. Disabling this allows use of models that do not support or are not very good at tool use. Some features will not work without tools. | +| **Access Control** | Set which teams, channels, and users can access this agent | #### LLM Specific Agent Settings -Some capabilities depend on the selected Service type and, for OpenAI Compatible and Azure, whether **Use Responses API** is enabled on that service. +Some capabilities are available depending on the selected Service and its configuration: | Setting | Description | |---------|-------------| -| **Enable Web Search** | Available for Anthropic, OpenAI, Google Gemini, and Google Vertex AI. For OpenAI Compatible and Azure, this setting is available when **Use Responses API** is enabled on the Service. Gemini and Vertex map this to Google Search grounding via the provider's Responses API. Allows the Agent to leverage the provider's native web search tool to respond with recent information. | -| **Reasoning Enabled** | Available for Anthropic, OpenAI, Google Gemini, and Google Vertex AI. For OpenAI Compatible and Azure, this setting is available when **Use Responses API** is enabled on the Service. Enables extended thinking or reasoning capabilities for complex tasks. For Gemini / Vertex, Bifrost maps a token budget to `thinkingConfig.thinkingBudget` and an effort level to `thinkingConfig.thinkingLevel` on Gemini 3.0+. | -| **Structured Output** | Available for Anthropic, OpenAI, OpenAI Compatible, and Azure. When enabled and a JSON schema is provided in the request, the model returns structured JSON matching that schema. Compatible model support is still required. | - -New agents enable native web search and structured output by default where the selected provider supports those features. For providers that don't support native tools, native tool selections are ignored. - -For Anthropic services, **Structured Output** and extended thinking can't be used at the same time. - -If you need an OpenAI-style endpoint without the Responses API path, use an **OpenAI Compatible** service and turn **Use Responses API** off for that service instead of using the **OpenAI** service type. - -#### Access tab - -Use this tab to control who can interact with and manage the agent: - -- **Channel access** controls which channels the agent can be mentioned in -- **User access** controls which users can interact with the agent -- **Agent admins** can edit and delete the agent; the agent creator is always an admin - -#### MCPs tab - -Use this tab to control which MCP tools the agent can use. This tab is available only when **Enable Tools** is turned on. - -- **Automatically enable all MCP tools** gives the agent access to every currently available MCP tool and any MCP tools added later. -- When **Automatically enable all MCP tools** is off, select the specific MCP tools the agent may use. -- If a previously selected MCP tool is no longer available, it is removed from the agent configuration when you save. +| **Enable Web Search** | Available for OpenAI (with Responses API enabled on the Service) and Anthropic. Allows the Agent to leverage the provider's native web search tool to respond with recent information. | +| **Reasoning Enabled** | Available for OpenAI (with Responses API) and Anthropic. Enables "thinking" or reasoning capabilities for complex tasks. | -Updating an agent's display name also updates the linked Mattermost bot display name. Deleting an agent deactivates the linked Mattermost bot account. - -Legacy bots previously stored in plugin configuration are migrated on startup into database-backed agents and then managed from the **Agents** page. Migrated agents don't have a creator and can be managed by system admins. +Select **Save** to create the agent. ### Custom instructions @@ -171,17 +116,17 @@ For example, you could list your organization's specific acronyms so the agent k ### Built-in web search configuration -The built-in web search tool lets agents retrieve current information from the internet when the model or deployment doesn't use the provider's own search. Prefer native provider web search when your service supports it. +The built-in web search tool allows agents to retrieve current information from the internet when answering user questions. This feature is designed for deployments using LLM models that don't provide their own native web search capabilities. #### When to use built-in web search -Built-in web search is intended for LLM models that lack native web search functionality. If your chosen model already provides native web search (such as OpenAI, Anthropic, Google Gemini, Google Vertex AI, or an OpenAI Compatible/Azure service with **Use Responses API** enabled), it's strongly recommended to use the provider's native implementation instead. Native web search tools typically offer: +Built-in web search is intended for LLM models that lack native web search functionality. If your chosen model already provides native web search (such as OpenAI with the Responses API or Anthropic's native search tool), it's strongly recommended to use the provider's native implementation instead. Native web search tools typically offer: - Better integration with the model - More reliable search results - Optimized performance -For configuration details on native web search with supported providers, see the [LLM Specific Agent Settings](#llm-specific-agent-settings) section above. +For configuration details on native web search with supported providers, see the [LLM Specific Settings](#llm-specific-settings) section above. #### Provider comparison @@ -274,6 +219,7 @@ Configure chunking options based on your needs: | **Chunking Strategy** | Sentences, Paragraphs, or Fixed Size | Choose based on your content type | | **Chunk Size** | 512-1024 tokens | Varies by strategy | | **Chunk Overlap** | 20-50 tokens | For better context continuity | +| **Minimum Size Ratio** | Default | Minimum ratio for chunk size validation | Run the initial indexing process after configuration. @@ -335,124 +281,21 @@ Post indexing occurs automatically during initial setup and when changing embedd - Trigger reindexing when changing embedding providers. - Check indexing status. -### OpenTelemetry tracing - -The plugin supports distributed tracing via [OpenTelemetry](https://opentelemetry.io/) to provide visibility into request latency, LLM call performance, tool execution, and error diagnosis. - -#### What gets traced - -When enabled, the plugin creates spans for: - -- **HTTP requests**: Every API call to the plugin, with method, route, and status code (via otelgin middleware) -- **LLM completions**: Provider, model, operation type, streaming status, input/output token counts, and errors -- **Tool execution**: Tool name, ID, resolution status, and errors for both built-in and MCP tools -- **MCP tool calls**: Remote MCP server and tool name -- **Semantic search**: Search queries and result retrieval -- **Web search**: Brave and Google search API calls -- **Post streaming**: Duration and context for streaming LLM responses to posts - -Spans are organized in a parent-child hierarchy that follows the request flow, so a single user message produces a trace like: - -```text -HTTP POST /post/:postid/react - └── process user request - ├── llm chat completion (provider=openai, model=gpt-4o, tokens=150/42) - ├── resolve tool (tool=web_search) - └── stream to post -``` - -#### Enabling tracing - -The plugin offers three trace output modes, configurable via **Trace Output** in the System Console: - -- **Off** — tracing disabled, zero overhead. -- **Server Logs** — finished spans are written to the Mattermost server log via the standard plugin logger. No collector required; pick this if you don't run Tempo, Jaeger, or another OTLP backend. -- **OTLP Endpoint** — spans are exported over OTLP gRPC to the endpoint configured in **OpenTelemetry Endpoint** (e.g. `localhost:4317`). Use this for full distributed tracing with a backend like Grafana Tempo or Jaeger. - -The setting can also be configured directly in the plugin configuration JSON: - -```json -{ - "telemetryOutput": "otlp", - "openTelemetryEndpoint": "your-collector:4317" -} -``` - -Valid values for `telemetryOutput` are `off`, `logs`, and `otlp`. When set to `off` (or omitted), the plugin uses a no-op tracer with zero overhead. The `openTelemetryEndpoint` field is only consulted when the mode is `otlp`. - -#### Local development with Grafana Tempo - -For local development and debugging, use the included Docker Compose file to run [Grafana Tempo](https://grafana.com/oss/tempo/) and Grafana: - -```bash -docker compose -f dev/docker-compose.otel.yml up -d -``` - -This starts: -- **Tempo** with OTLP gRPC on port `4317` and OTLP HTTP on port `4318` -- **Grafana** at `http://localhost:3001` with the Tempo datasource preprovisioned (anonymous Admin, no login required) - -Configure the plugin with endpoint `localhost:4317`, then interact with the bot. Open Grafana → **Explore** → **Tempo** and search by service name `mattermost-ai-agents`, or paste a trace ID directly. - -Grafana is mapped to port `3001` (not the default `3000`) so it does not collide with Mattermost's webapp dev server or the `mattermost-server` build/docker-compose stack. - -To stop the stack: - -```bash -docker compose -f dev/docker-compose.otel.yml down -``` - -Add `-v` to also discard accumulated traces. - -#### Production deployment - -For production, send traces to your existing OpenTelemetry Collector or directly to a backend: - -- **OpenTelemetry Collector**: Point the endpoint to your collector's OTLP gRPC address. The collector can then export to Jaeger, Zipkin, Datadog, Grafana Tempo, AWS X-Ray, or any other supported backend. -- **Direct export**: Point the endpoint directly to a backend that supports OTLP gRPC (e.g., Grafana Tempo at `tempo:4317`). - -The connection currently uses insecure (non-TLS) gRPC. For TLS-terminated endpoints, route through an OpenTelemetry Collector with TLS configured. - -#### Custom span attributes - -Traces include these semantic attributes for filtering and analysis: - -| Attribute | Description | Example | -|-----------|-------------|---------| -| `agents.llm.provider` | LLM provider name | `openai`, `anthropic` | -| `agents.llm.model` | Model identifier | `gpt-4o`, `claude-3-opus` | -| `agents.llm.operation` | Operation type | `conversation`, `title_generation` | -| `agents.llm.input_tokens` | Input token count | `150` | -| `agents.llm.output_tokens` | Output token count | `42` | -| `agents.tool.name` | Tool being called | `web_search`, `read_channel` | -| `agents.tool.id` | Tool call identifier | `call_abc123` | -| `agents.mcp.server` | MCP server name | `github-server` | -| `agents.mcp.tool` | MCP tool name | `search_issues` | -| `agents.user.id` | Requesting user ID | `abc123def456` | -| `agents.channel.id` | Channel ID | `abc123def456` | -| `agents.post.id` | Post ID | `abc123def456` | -| `agents.thread.root_post.id` | Root post ID for thread correlation | `abc123def456` | - ### Backup and restore -The plugin stores agent data across both plugin configuration and plugin database tables. To backup: - -1. Ensure your regular Mattermost backup includes plugin configuration data. -2. Include plugin database tables in your normal backup and restore process. In particular: - - `Agents_UserAgents` for agents created or managed from the **Agents** page - - `LLM_CustomPrompts` and `LLM_CustomPromptPins` for custom prompt templates and prompt pins -3. For larger deployments, consider backing up indexed vector data separately. +The plugin configuration is stored in the Mattermost database. To backup: -Restoring only plugin configuration isn't sufficient to restore agents managed from the **Agents** page. +1. Ensure your regular Mattermost backup includes plugin configurations +2. For larger deployments, consider backing up indexed vector data separately ### Configuration format -The plugin uses a service-based architecture: +The plugin uses a service-based architecture stored in the Mattermost database at `PluginSettings.Plugins["mattermost-ai"]`: -- `PluginSettings.Plugins["mattermost-ai"]["config"]` stores plugin-wide settings and AI service configurations, including `defaultBotName` -- Agents are stored separately in the `Agents_UserAgents` table +- **Services** define LLM provider configurations (API keys, models, endpoints) +- **Bots** reference services by ID and define agent personalities and access controls -This separation allows multiple agents to share the same LLM service configuration while keeping agent lifecycle and access data out of `config.bots`. +This separation allows multiple bots to share the same LLM service configuration. **Configuration structure:** ```json @@ -467,14 +310,22 @@ This separation allows multiple agents to share the same LLM service configurati "defaultModel": "gpt-4o" } ], - "defaultBotName": "ai" + "bots": [ + { + "id": "bot-001", + "name": "ai", + "displayName": "AI Assistant", + "serviceID": "550e8400-e29b-41d4-a716-446655440000", + "customInstructions": "You are a helpful assistant." + } + ] } } ``` -**Supported service types:** `openai`, `anthropic`, `azure`, `openaicompatible`, `asage`, `cohere`, `mistral`, `scale` +**Supported service types:** `openai`, `anthropic`, `azure`, `openaicompatible`, `asage`, `cohere`, `mistral` -**Legacy format:** Older configurations that stored bots in `config.bots`, or embedded service objects within bots, are migrated on plugin startup. After legacy bot migration completes, stored `config.bots` entries are removed to avoid duplicate bot registration. +**Legacy format:** Older configurations with embedded service objects within bots are automatically migrated to the current format on plugin startup. ## Troubleshooting @@ -487,83 +338,69 @@ Enhanced logging can help diagnose issues: 3. Enable debug logging in the plugin configuration for additional diagnostic information. 4. For production environments, disable debug logging and LLM Trace after troubleshooting to reduce log volume. -### Tool execution failures +## Integrations -When a tool call fails, the agent does not always stop immediately. It may continue with a follow-up model turn so it can recover, explain the failure, or answer without that tool. +Currently integrations are limited to direct messages between users and the agents. The integrations won't operate from within public, private, or group message channels. -To avoid endless retries, the plugin enforces a limit of **three consecutive failed tool attempts**. After that, no further tool calls are made for that sequence; the model is instructed to describe the latest error and ask the user for guidance or any missing information such as permissions, identifiers, or configuration details. +### Built-in tool integrations -When users report repeated tool failures, use **LLM Trace** and debug logging to inspect tool errors and upstream responses. Also verify integration configuration such as API keys, endpoints, MCP connectivity, and third-party authorization, and confirm the user can access the underlying Mattermost resources the tool targets. +#### Server Search -## Integrations +- **Function**: Semantic search across Mattermost content. +- **Requirements**: Embedding search must be configured and enabled. +- **Security**: Respects user permissions - users only see content they have access to. -Integrations are available in direct messages by default. If you enable the experimental **Enable Channel Mention Tool Calling** setting, @mentioning an agent in a public channel can also allow tool calling there. Native provider web search in public and private channels is controlled separately by **Allow native web search in channels**. +#### User Lookup -## Model Context Protocol (MCP) Integration +- **Function**: Look up Mattermost user information by username +- **Data Available**: Username, full name, email, nickname, position, locale, timezone, last activity, status +- **Permissions**: Requires `VIEW_MEMBERS` permission -The Model Context Protocol (MCP) integration lets Agents use tools exposed by MCP servers, including the embedded Mattermost tools and optional remote servers. +#### Jira Integration -The MCP client and the embedded Mattermost MCP server are always enabled. Admins manage remote MCP servers, connection timeout, and per-tool enabled state and approval policies from the MCP UI in the System Console. Agent-level MCP access is configured separately on each agent's **MCPs** tab. +- **Function**: Fetch issues from public Jira instances +- **Requirements**: No additional configuration needed +- **Usage**: Provide Jira instance URL and issue keys +- **Data Retrieved**: Issue summary, description, status, assignee, comments, metadata -### Configuration +#### GitHub Integration -1. Navigate to **System Console > Plugins > Agents > Model Context Protocol (MCP)**. -2. Use the **Configuration** tab for: +- **Function**: Fetch GitHub issues and pull requests +- **Requirements**: Mattermost GitHub plugin must be installed and running +- **Authentication**: Users must be logged into GitHub through the Mattermost GitHub plugin +- **Access**: Works with both public and private repositories (based on user permissions) +- **Data Retrieved**: Issue/PR title, number, state, submitter, body content - - **Enable Mattermost MCP Server (HTTP)**: Optional HTTP endpoint for external MCP clients. See [Mattermost MCP Server](#mattermost-mcp-server). - - **Connection Idle Timeout (minutes)**: Timeout for inactive user MCP connections (default: 30 minutes). - - Remote MCP servers, including URL, custom headers, OAuth client settings, and per-server enablement. +**Security Note**: All tool integrations are restricted to direct messages to maintain security boundaries and require explicit user approval before execution. -3. Use the **Tools** tab to review discovered tools and set each tool's enabled state and approval policy. -4. When creating or editing an agent on the **Agents** page, use the **MCPs** tab to choose whether that agent can use all MCP tools automatically or only a selected set of tools. +## Model Context Protocol (MCP) Integration -The **Tools** tab refreshes automatically after the current user connects or disconnects an OAuth-backed MCP server. Because MCP OAuth connections are per-user, this live refresh applies only to the user who completed the connect or disconnect action. +The Model Context Protocol (MCP) integration allows Agents to connect to external tools and services through standardized MCP servers. This feature enables expanding AI capabilities with custom integrations. -You can't disable MCP entirely from the System Console. To limit access, disable individual tools or change their policy in the **Tools** tab. +### Configuration +1. Navigate to **System Console > Plugins > Agents > MCP Servers**. +2. Enable MCP integration by setting **Enable MCP** to **True**. +3. Configure connection settings: + + - **Idle Timeout**: Set timeout in minutes for inactive client connections (default: 30 minutes) ### Add MCP servers -1. On the **Configuration** tab, select **Add Remote MCP Server** to configure a new server. +1. Select **Add MCP Server** to configure a new server. 2. Configure server settings: - **Server URL**: The endpoint URL for your MCP server. - **Custom Headers**: Additional headers required by your MCP server (optional). - **Server Name**: Descriptive name for the server (auto-generated if not provided). -3. Select **Save** to add the server. - -### Configure OAuth-backed servers for agents - -When you create or edit an agent from the **Agents** page, the **MCPs** tab in the full-page agent editor lists the MCP servers available to that agent. If an OAuth-backed server is not connected for your account yet, the row shows a **Connect** button so you can complete the provider sign-in flow without leaving the editor. The MCPs tab refreshes automatically after you connect or disconnect, so you don't need to reopen it to see updated server status. - -If a disconnected OAuth-backed server currently exposes no tools, you can still toggle that server on while configuring the agent. Saving the agent in this state grants the agent access to every tool that server exposes after a user connects to that provider. - -The **Automatically enable all MCP tools** option remains the broadest setting. When enabled, the agent can use every currently available MCP tool as well as MCP tools added later. - -Enabling a server or tool for an agent controls what the agent is allowed to use, but it does not bypass tool approval policies. Tool execution still follows the policy configured in the **Tools** tab and each user's Mattermost and provider permissions. +4. Select **Save** to add the server. ### Management - **Connection Management**: The system automatically manages user connections to MCP servers - **Idle Cleanup**: Inactive client connections are automatically closed after the configured timeout - **Per-User Connections**: Each user gets their own connection to MCP servers for security and isolation -- **Tool Policies**: Use the **Tools** tab to allow, require approval for, or disable individual tools -- **Agent Scoping**: The RHS **Tools** popover only shows MCP providers allowed for the selected agent. Tool use is still subject to admin tool policies and the user's Mattermost permissions - -### OAuth-backed MCP servers - -Some MCP servers require OAuth per Mattermost user. For those servers, the plugin exposes `needsOAuth` and `authURL` to the Agents webapp so the UI can show when authorization is required and where to begin the flow. The webapp starts OAuth through the plugin route `GET /plugins/mattermost-ai/mcp/oauth//start` and can clear the current user's stored token with `DELETE /plugins/mattermost-ai/mcp/oauth/`. - -**Agents panel (web and desktop):** In the Agents right-hand sidebar, start a new chat and open **Tools**. OAuth-backed servers show **Connect** when the signed-in user is not authenticated, and **Disconnect** when an OAuth session applies. - -**System Console (admin tool configuration):** On **System Console > Plugins > Agents > MCP Servers**, expanding an OAuth-backed server shows that you must authenticate to fetch that server's tool list and configure per-tool approval policies. That sign-in only applies to your administrator account. Each end user must authenticate separately, even after an admin has connected in the System Console. - -**Conversations:** The plugin no longer posts ephemeral in-channel or in-thread messages to prompt MCP OAuth. Users should use the Agents webapp **Tools** menu to view connection state and run **Connect** or **Disconnect**. - -**Mobile and other clients:** MCP OAuth is not initiated from the mobile app or other clients that do not use the Agents webapp. Users need Mattermost web or desktop to connect OAuth-backed MCP servers. - -**Custom MCP OAuth setups:** If the OAuth start URL includes a `resource_metadata` query parameter, it is accepted only when its origin matches the origin of the configured MCP server **Server URL**. This prevents cross-origin metadata injection during discovery. ### Atlassian MCP server authorization @@ -591,13 +428,11 @@ After adding the domain, wait 1-2 minutes for changes to propagate before users For more information, see [Atlassian's documentation on MCP server settings](https://support.atlassian.com/security-and-access-policies/docs/control-atlassian-rovo-mcp-server-settings/). -> **Note:** By default, the plugin doesn't render AI-generated Markdown links (for example, JIRA ticket links) as clickable links. URLs are displayed in plain text to reduce potential phishing and data exfiltration risk. If an admin enables **Render AI-generated links** (`allowUnsafeLinks`), AI-generated links may become clickable; enable this only with appropriate trust boundaries and security mitigations in place. +> **Note:** The plugin currently doesn't render Markdown links (e.g., JIRA ticket links) in bot responses. URLs are displayed in plain text rather than as clickable Markdown-rendered links. This is not a bug but intended security behavior to prevent potential data exfiltration through links. While this limitation exists, improvements to link handling are being considered for future development. ## Mattermost MCP Server -The Mattermost MCP Server enables AI agents and external applications to interact with your Mattermost instance through the Model Context Protocol (MCP). This is a standardized protocol that allows AI assistants to read messages, search content, create posts, and manage channels and teams programmatically. - -**Standalone MCP server (separate process / stdio):** Running the standalone `mattermost-mcp-server` binary outside the Mattermost server is for **development and local use only** and is **not** intended for production. Production deployments should rely on the embedded Mattermost MCP server and the supported configuration in this plugin (System Console, HTTP endpoint for external clients, and agent MCP settings below). +The Mattermost MCP Server enables AI agents and external applications to interact with your Mattermost instance through the Model Context Protocol (MCP). This is a standardized protocol that allows AI assistants to read messages, search content, create posts, and manage channels and teams programmatically. ### Overview @@ -636,17 +471,21 @@ The MCP server provides the following tools to AI agents and external clients: ### Deployment +![MCP Server Configuration](/agents/docs/img/system-console-mcp.png) + #### For AI Agents -The embedded Mattermost MCP server is available automatically to configured AI agents. No System Console switch is required to enable embedded MCP for in-product agents. +To set up an embedded MCP server providing Mattermost AI agents with direct access to Mattermost functionality: -Use **System Console > Plugins > Agents > Model Context Protocol (MCP)** to configure remote MCP servers, the idle timeout, the optional HTTP endpoint for external clients, and per-tool enablement and approval policies. Then use each agent's **MCPs** tab on the **Agents** page to either automatically enable all MCP tools or restrict that agent to specific tools. +1. Go to **System Console > Plugins > Agents > MCP Servers**. +2. Set **Enable Embedded Server** to **True**. +3. When enabled, all configured agents can access Mattermost tools. -Configured agents can use these tools subject to their own MCP settings, admin tool policies, user permissions, and any required approval flow. +Agents will automatically use these tools when appropriate to complete user requests. #### For External Clients -You can enable external MCP clients, such as Claude web, Claude Code, or other MCP-compatible applications, to interact with your Mattermost instance. This HTTP server is separate from the always-on embedded MCP server used by Mattermost Agents. +You can enable external MCP clients, such as Claude web, Claude Code, or other MCP-compatible applications, to interact with your Mattermost instance. **Requirements:** - Mattermost Server v11.2 or later @@ -656,7 +495,7 @@ You can enable external MCP clients, such as Claude web, Claude Code, or other M To enable an external MCP client: -1. Go to **System Console > Plugins > Agents > Model Context Protocol (MCP)** +1. Go to **System Console > Plugins > Agents > MCP Servers** 2. Set **Enable Mattermost MCP Server (HTTP)** to **True**. The MCP server will be available at: `https://your-mattermost-server/plugins/mattermost-ai/mcp-server/mcp` diff --git a/source/_generated/agents/docs/user_guide.md b/source/_generated/agents/docs/user_guide.md index d6323d7b159..0d061fda5a9 100644 --- a/source/_generated/agents/docs/user_guide.md +++ b/source/_generated/agents/docs/user_guide.md @@ -10,16 +10,12 @@ You can access AI features in Mattermost in the following ways: ### Web and desktop -Access AI features in one of the following ways: +Access AI features through the right pane in one of the following ways: - Select the **Agents** icon in the apps sidebar. - @mention an AI bot in any channel where you have access (such as `@copilot`). -- Open the **AI Actions** menu in the message composer to insert saved **Custom prompts** templates or open **Manage prompts**. - Use the **AI Actions** menu by hovering over the first message in any conversation thread (see [license requirements](https://docs.mattermost.com/administration-guide/configure/agents-admin-guide.html#license-requirements)) - Use the **Ask AI** option in channels with unread messages (see [license requirements](https://docs.mattermost.com/administration-guide/configure/agents-admin-guide.html#license-requirements)) -- Use **Ask Agents about this channel** in a channel header to summarize recent activity, focus on a date range, or ask a question about the current channel. See [Channel Summaries](features/channel_summaries.md). - -![AI Actions menu in the message composer, including the Custom prompts entry.](img/ai-actions-menu-composer.png) ### Mobile @@ -31,77 +27,29 @@ Start or open a direct message with the Agent bot. If your system admin has conf You can have conversations with Agents in several ways: -**Agents pane**: Use the Agents right-hand pane for a streamlined experience. Begin with suggested prompts or pinned custom prompt buttons, or engage in a private thread with an Agent for a tailored experience. If you have follow-up questions or need further insights, simply ask. You can also attach files for AI analysis or reference. +**Agents pane**: Use the Agents right-hand pane for a streamlined experience. Begin with suggested prompts, or engage in a private thread with an Agent for a tailored experience. If you have follow-up questions or need further insights, simply ask. You can also attach files for AI analysis or reference. **Direct messages**: Start a direct message with an Agent bot to have a private conversation. Chat privately with an Agent in direct message threads like you would any other Mattermost user. -**Channel mentions**: [@mention](https://docs.mattermost.com/collaborate/mention-people.html) Agent bots by their username, such as `@copilot`, in any thread to bring Agents capabilities to your conversation. The bot responds in a thread to keep channels organized, and other team members can view and contribute to the conversation. An Agent can help extract information quickly or transform discussions into charts, resources, documentation, and more, and can find action items and open questions in new messages. When you @mention an Agent in a thread, it uses earlier thread context up to that mention, including earlier posts in the thread. Later replies posted after that mention, and temporary placeholder bot posts, aren't included in that request. - -When you attach files in the Agents pane, direct messages, or channel @mentions, Agents can use them as conversation context. Images are included only when vision is enabled for the bot. Other files contribute text only when Mattermost can read text from them, such as plain-text files or files with extracted text. Very large attachment text may be shortened, and if one attachment can't be read, that attachment is skipped while the conversation continues. - -> **Note:** Whether AI-generated links are clickable depends on your system admin configuration. Treat links in AI responses with caution and verify destinations before opening them. +**Channel mentions**: [@mention](https://docs.mattermost.com/collaborate/mention-people.html) Agent bots by their username, such as `@copilot`, in any thread to bring Agents capabilities to your conversation. The bot responds in a thread to keep channels organized, and other team members can view and contribute to the conversation. An Agent can help extract information quickly or transform discussions into charts, resources, documentation, and more, and can find action items and open questions in new messages. ### Select a bot If multiple Agent bots are configured for your Mattermost workspace, select your preferred bot in the Agents pane or @mention specific bots by name in channels. -### Use custom prompt templates - -Custom prompts are saved prompt templates that you can reuse from the message composer or from pinned buttons in the Agents pane. - -To manage custom prompts: - -1. Open the message composer in any channel or direct message. -2. Select **AI Actions**. -3. Open **Custom prompts**, then select **Manage prompts**. -4. Select **Create new** to open the prompt editor and add a prompt with an **Action Title**, optional description, and template. -5. Choose **Public** to share the prompt with other users, or **Private** to keep it visible only to you. -6. Pin or unpin prompts directly from the prompt list. Pinned prompts appear as shortcuts in the Agents pane. - -The **All Prompts** tab shows prompts you created plus shared prompts from other users. The **Your Prompts** tab shows only prompts you created. Selecting a prompt from either list opens a dedicated prompt view inside the modal, with a back arrow to return to the list and the prompt name as the title. Shared prompts from other users open read-only. Only the prompt creator can edit or delete a prompt. Prompt titles can be up to 64 characters, and every prompt requires a template. - -When you select a saved prompt from **Custom prompts**, Mattermost renders the template with the current context and inserts the result into your draft. If you use this menu outside a bot direct message, Mattermost adds the currently selected bot mention before the rendered text. Pinned prompts in the Agents pane render the current saved template and send it immediately as a message. - -Custom prompt templates support the following variables: - -| Variable | Inserts | -|----------|---------| -| `{{.Username}}` | Your Mattermost username | -| `{{.FirstName}}` | Your first name | -| `{{.LastName}}` | Your last name | -| `{{.Channel}}` | The current channel display name | -| `{{.ChannelName}}` | The current channel name | -| `{{.Team}}` | The current team display name | -| `{{.TeamName}}` | The current team name | -| `{{.Time}}` | The current UTC time | -| `{{.BotName}}` | The selected agent display name, when available | - -If a value isn't available in the current context, the rendered prompt leaves it blank. - -### Use tools - -When Agents use external tools or integrations, Mattermost may prompt you to review tool usage based on the tool approval policy configured by your system admin. When review is required, only the person who requested the Agent interaction can accept or reject pending tools. For those pending tools, you'll see a card showing the tool name and description, arguments being passed to the tool, and **Accept** and **Reject** options. If multiple tools are waiting for a decision, Mattermost may also show **Accept all** and **Reject all** controls. - -By default, tool calls are available in direct messages. If your system admin enables the experimental **Enable Channel Mention Tool Calling** setting, some tools can also run in channels. Depending on the configured tool policy, each tool call may require approval before execution or run automatically. A single Agent response can include both auto-approved tools and tools still waiting for approval. In that case, the auto-approved badge applies only to the individual tool that ran automatically, while pending tools continue to show **Accept** and **Reject** options. Tool results are shown after execution, and if a result needs a visibility decision, you'll see **Share** and **Keep private** options. - -Only the person who started the conversation can approve or reject tool calls. In direct messages with an agent, approved tool results are shared automatically because only you can view that conversation. - -In channels, tool approval can be a two-step process. After you approve a tool call and it runs, Mattermost can prompt you again to decide whether the tool arguments and results should be shared with the channel or kept private. If you choose **Keep Private**, other channel members don't see that tool data, and the channel-visible follow-up response is generated without the private content. +### Approve tools -If a tool execution fails, the Agent can continue with a follow-up response instead of stopping immediately. After three consecutive failed tool executions, the Agent stops calling further tools and is instructed to explain the latest error and ask you for guidance or any missing information. A successful tool execution resets that count. +When Agents use external tools or integrations, you may be prompted to approve tool usage for security. When a tool is called, you'll see a card showing the tool name and description, arguments being passed to the tool, and **Approve/Reject** options. -On web and desktop, start a new chat in the Agents right-hand pane and open the **Tools** menu in the header. The menu lists configured tool providers. For MCP servers that use OAuth, you'll see **Connect** when you're not authenticated and **Disconnect** when an OAuth session applies. You can turn individual providers on or off from this menu, and your choices are saved as your personal preferences. Mattermost doesn't send OAuth connection prompts as ephemeral posts in the conversation; use the **Tools** menu to check connection state and complete **Connect** or **Disconnect** flows. +For security, tool calls are only available in direct messages and each tool call requires explicit approval before execution. You can review tool arguments before approving, and tool results are shown after successful execution. -> **Note:** The Mattermost mobile apps don't currently support starting MCP OAuth connections from the Agents experience. Use web or desktop to connect OAuth-backed MCP providers. +Available tools in direct messages include: -Depending on your workspace configuration, available tools in direct messages, and in channels when enabled by your system admin, can include: - -- Mattermost MCP tools, including tools to search posts and find users in Mattermost, when your system admin has enabled the Mattermost MCP server for Agents -- MCP tools provided by other configured MCP servers, if enabled - -Tool availability depends on your user permissions, provider connection status, and workspace configuration. - -Some MCP providers require each user to connect their own account before those tools become available. When that applies, open the **Tools** menu in the Agents pane or RHS, select **Connect** for the provider, and wait for the list to refresh with the newly available tools. +- Server search (semantic search across your Mattermost instance) +- User lookup (find information about Mattermost users) +- GitHub integration (the ability to fetch GitHub issues and pull requests requires the [GitHub plugin](https://docs.mattermost.com/integrate/github.html)) +- [Jira integration](https://docs.mattermost.com/integrate/jira.html) (retrieve Jira issues from public instances) +- MCP tools (external tools provided by configured MCP servers if enabled). Tool availability depends on your user permissions and system configuration. ## Analyze threads and channels @@ -129,9 +77,7 @@ To summarize unread Mattermost channels: 2. Select **Ask AI**. 3. Select **Summarize new messages**. -The channel summary is generated in the Agents pane, and only you can view the summary. - -For more flexible channel analysis options, including **Ask Agents about this channel**, prompts, and date ranges, see [Channel Summaries](features/channel_summaries.md). +The channel summary is generated in the Agents pane, and only you can view the summary. Channel summaries include citation links that reference specific messages from the channel. Select a citation link to open a popover preview of the referenced message without navigating away from the channel. ## Search with AI @@ -145,9 +91,7 @@ Contact your system admin if this feature isn't available for your Mattermost in ## Analyze images -For AI models with vision capabilities, attach an image file to your message when chatting with an Agent or @mentioning an Agent in a channel to ask questions about the image or request analysis. The Agent responds based on the visual content. - -In channel threads, a later @mention can also include image attachments from earlier posts in the same thread when those posts are part of the thread context. +For AI models with vision capabilities, attach an image file to your message when chatting with an Agent to ask questions about the image or request analysis. The Agent responds based on the visual content. Your system admin must enable vision capabilities for your bot, and the underlying AI model must support vision features. @@ -163,24 +107,3 @@ To summarize a Mattermost call recording: The meeting summary is generated and shared as a direct message with the person who requested the meeting summary. Both call recordings and recorded meeting summarization require a license. See [license requirements](https://docs.mattermost.com/administration-guide/configure/agents-admin-guide.html#license-requirements) for details. Contact your system admin if these features aren't available for your Mattermost instance. - - -## Summarize Zoom meetings in Mattermost - -The Zoom plugin must be [enabled and configured](https://docs.mattermost.com/integrate/zoom.html) by a Mattermost system admin and Zoom cloud recordings and transcripts must be enabled before you can summarize Zoom meetings. - -If the Zoom plugin is enabled and configured, subscribe a Mattermost channel to a Zoom meeting (`/zoom subscription add [meeting ID]`) and record the meeting. Once the recording and transcription are available, they are automatically shared back to the channel. - -Use Mattermost to turn Zoom meeting recordings into actionable AI-generated summaries with any model of your choosing, including your own. By summarizing your Zoom meeting recordings in Mattermost, you can easily share the insights with your team and the broader organization, enhancing communication and productivity without sacrificing data privacy and control. - -To summarize a Zoom meeting in Mattermost: - -1. Subscribe a Mattermost channel to a recurring Zoom meeting with `/zoom subscription add [meeting ID]` or start a meeting using the Zoom button in the Mattermost right-hand sidebar (RHS). -2. Record the Zoom meeting. -3. Once the meeting ends and the transcript file is posted to Mattermost, select the **Create meeting summary** option located directly above the file. - -![Select the Create meeting summary option to summarize your Zoom meeting in Mattermost.](img/create-meeting-summary-zoom.png) - -4. The meeting summary is generated and shared as a direct message with the person who requested the meeting summary. - -![Easily share the updates from your Zoom meetings with your team and broader organization by turning recordings into detailed summaries at the click of a button.](img/copilot-Zoom-Meeting-Summary.png) From a7e9ad0c10191c0a9068ba7f0777e7b940fb48c7 Mon Sep 17 00:00:00 2001 From: Harshil Sharma Date: Fri, 14 Aug 2026 11:44:22 +0530 Subject: [PATCH 3/6] rephrased some sections --- .../comply/embedded-json-audit-log-schema.rst | 2 +- .../comply/post-delivery-audit-logging.rst | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/administration-guide/comply/embedded-json-audit-log-schema.rst b/source/administration-guide/comply/embedded-json-audit-log-schema.rst index 80dbca3cf75..e4e11ffbb35 100644 --- a/source/administration-guide/comply/embedded-json-audit-log-schema.rst +++ b/source/administration-guide/comply/embedded-json-audit-log-schema.rst @@ -359,7 +359,7 @@ Posts & Content Events Post Delivery Events ~~~~~~~~~~~~~~~~~~~~ -From Mattermost v12.0, ``postDelivered`` is written at the ``audit-delivery`` log level rather than alongside the other audit log levels, and only when :doc:`post delivery audit logging ` is enabled. See that page for the record format, the payload fields, and the full set of delivery mechanisms. +Mattermost v12.0 introduces the ``postDelivered`` audit log event, which records each delivery of a message's content to a user or an integration. It's emitted only when :doc:`post delivery audit logging ` is enabled, which is disabled by default. Unlike the other audit log events on this page, ``postDelivered`` is emitted at the dedicated ``audit-delivery`` log level and so requires its own audit log target. See that page for the record format, the payload fields, and the full set of delivery mechanisms. +----------------------------------+-------------------------------------------------------------------+ | **Event Name** | **Description** | diff --git a/source/administration-guide/comply/post-delivery-audit-logging.rst b/source/administration-guide/comply/post-delivery-audit-logging.rst index 8d5a9ad7711..3402af825c6 100644 --- a/source/administration-guide/comply/post-delivery-audit-logging.rst +++ b/source/administration-guide/comply/post-delivery-audit-logging.rst @@ -10,7 +10,7 @@ From Mattermost v12.0, Mattermost can record an audit log entry each time a mess Post delivery audit logging is currently in :ref:`Beta `. -Delivery records are ordinary audit log records, written through the existing audit logging pipeline to whichever audit log targets you've configured. Mattermost never reads them back. They're not shown anywhere in the Mattermost interface, they're not included in any report, and there's no REST API for retrieving them. Consuming delivery records is your responsibility, using whatever tooling already ingests your Mattermost audit logs. Retention is whatever your audit log pipeline provides. +Delivery records are ordinary audit log records, written through the existing audit logging pipeline to whichever audit log targets you've configured. Before you begin ---------------- @@ -18,12 +18,12 @@ Before you begin Post delivery audit logging requires all of the following: - A Mattermost Enterprise Advanced license. -- The `feature flag `_ ``MM_FEATUREFLAGS_POSTDELIVERYTRACKING``, which is disabled by default. **Restart the server after enabling the feature flag**, because the delivery tracking API endpoints are registered only at startup. +- The `feature flag `_ ``MM_FEATUREFLAGS_POSTDELIVERYTRACKING``, which is disabled by default. **Restart the server after enabling the feature flag**. - An audit log target that consumes the ``audit-delivery`` log level. .. important:: - Enabling post delivery audit logging on its own produces no output. Delivery records are discarded until an audit log target consumes the ``audit-delivery`` log level, and log volume increases substantially once one does. Configure the target before you enable the feature. + Enabling post delivery audit logging on its own produces no output. Delivery records are discarded until an audit log target consumes the ``audit-delivery`` log level. Configure the target before you enable the feature. The log volume increases substantially once these audit logs are enabled. Configure an audit log target ----------------------------- From 06c6278f3ee995369d11988253e84094828e0af9 Mon Sep 17 00:00:00 2001 From: Harshil Sharma Date: Fri, 14 Aug 2026 12:16:06 +0530 Subject: [PATCH 4/6] copilot comment fixes --- .../compliance-with-mattermost.rst | 2 +- .../comply/post-delivery-audit-logging.rst | 4 ++- .../environment-configuration-settings.rst | 2 +- .../configure/site-configuration-settings.rst | 36 ++++++++++--------- .../manage/admin/content-flagging.rst | 20 +++++++---- .../administration-guide/manage/logging.rst | 13 +++---- 6 files changed, 45 insertions(+), 32 deletions(-) diff --git a/source/administration-guide/compliance-with-mattermost.rst b/source/administration-guide/compliance-with-mattermost.rst index 10eff5ddea8..f311fdeb4f3 100644 --- a/source/administration-guide/compliance-with-mattermost.rst +++ b/source/administration-guide/compliance-with-mattermost.rst @@ -23,5 +23,5 @@ Mattermost is purpose-built to help enterprises keep sensitive data safe and com * :doc:`Data retention ` - Control how long data is stored in Mattermost with global and custom retention policies to meet data retention compliance requirements. * :doc:`Export channel data ` - Migrate data between systems and back data up for operational continuity. * :doc:`Legal Hold ` - Preserve relevant Mattermost information when litigation is anticipated. -* :doc:`JSON audit log schema ` - Learn how to configure Mattermost audit logging using a JSON object. +* :doc:`JSON audit log schema ` - Learn the JSON structure of Mattermost audit log entries. * :doc:`Post delivery audit logging ` - Record an audit log entry each time a message is delivered to a user, to establish which users a given message reached. \ No newline at end of file diff --git a/source/administration-guide/comply/post-delivery-audit-logging.rst b/source/administration-guide/comply/post-delivery-audit-logging.rst index 3402af825c6..443936ec833 100644 --- a/source/administration-guide/comply/post-delivery-audit-logging.rst +++ b/source/administration-guide/comply/post-delivery-audit-logging.rst @@ -202,7 +202,9 @@ Mattermost records one entry for each message delivered to each recipient, with Delivery records are an append-only event stream, not a deduplicated list of who has seen a message. The same combination of user, message, and mechanism recurs, because every time a user revisits a channel the same page of messages is delivered again. Each record is a genuine delivery with its own timestamp. -To build a distinct list of the users a message was delivered to, deduplicate on ``actor.user_id``, ``meta.post_id``, and ``meta.mechanism``, and treat the earliest timestamp in each group as the first delivery. +Deduplicate on ``actor.user_id``, ``meta.post_id``, and ``meta.mechanism`` to get one entry per recipient, message, and delivery mechanism, taking the earliest timestamp in each group as the first delivery by that mechanism. A recipient who received the same message by more than one mechanism — for example ``push`` and then ``product`` — has one entry per mechanism. + +To reduce that to a distinct list of the users a message reached, drop ``meta.mechanism`` from the key and deduplicate on ``actor.user_id`` and ``meta.post_id`` alone. Keep the following in mind when working with delivery records: diff --git a/source/administration-guide/configure/environment-configuration-settings.rst b/source/administration-guide/configure/environment-configuration-settings.rst index 7df3daa9634..60f46882f6d 100644 --- a/source/administration-guide/configure/environment-configuration-settings.rst +++ b/source/administration-guide/configure/environment-configuration-settings.rst @@ -3932,7 +3932,7 @@ Output audit logs to multiple targets - See the :doc:`Mattermost logging ` documentation for details on advanced logging configuration. These targets have been chosen as they support the vast majority of log aggregators, and other log analysis tools, without needing additional software installed. - Audit logs are recorded asynchronously to reduce latency to the caller. - Advanced audit logging supports hot-reloading of logger configuration. - - From Mattermost v12.0, the ``audit-delivery`` log level (ID ``104``) isn't written by the built-in audit log file target. To capture :doc:`post delivery audit records `, add a target for the level here. + - From Mattermost v12.0, the ``audit-delivery`` log level isn't written by the built-in audit log file target, so :ref:`post delivery audit records ` are discarded unless you add a target here whose ``levels`` list includes ``{"id": 104, "name": "audit-delivery"}``. ---- diff --git a/source/administration-guide/configure/site-configuration-settings.rst b/source/administration-guide/configure/site-configuration-settings.rst index fab8f82a080..b79bc3be22f 100644 --- a/source/administration-guide/configure/site-configuration-settings.rst +++ b/source/administration-guide/configure/site-configuration-settings.rst @@ -2259,39 +2259,41 @@ Team administrators as reviewers | as reviewers. | | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ -From Mattermost v12.0, the following settings control post delivery audit logging, which records an audit log entry each time a message is delivered to a user. Delivery records require an audit log target that consumes the ``audit-delivery`` log level. See :doc:`Post delivery audit logging ` for details. +From Mattermost v12.0, the following settings control post delivery audit logging, which records an audit log entry for each delivery of a message in an eligible channel. Delivery records require an audit log target that consumes the ``audit-delivery`` log level. See :doc:`Post delivery audit logging ` for details. -.. note:: +.. important:: - Post delivery audit logging is currently in :ref:`Beta `, and requires the `feature flag `_ ``MM_FEATUREFLAGS_POSTDELIVERYTRACKING``. Restart the server after enabling the feature flag. + Post delivery audit logging is currently in :ref:`Beta `. It requires the `feature flag `_ ``MM_FEATUREFLAGS_POSTDELIVERYTRACKING``, which is disabled by default, and a server restart after you enable it. It also requires an audit log target that consumes the ``audit-delivery`` log level. .. config:setting:: delivery-tracking-enable - :displayname: Enable post delivery audit logging (Content flagging) - :systemconsole: Site Configuration > Content Flagging + :displayname: Enable post delivery audit logging (Data Spillage Handling) + :systemconsole: Site Configuration > Data Spillage Handling :configjson: .DeliveryTrackingSettings.Enable :environment: MM_DELIVERYTRACKINGSETTINGS_ENABLE - :description: Record an audit log entry each time a message is delivered to a user. Default is **false**. + :description: Record an audit log entry for each delivery of a message in an eligible channel. Default is **false**. - - **true**: An audit log entry is recorded each time a message is delivered to a user. + - **true**: An audit log entry is recorded for each delivery of a message in an eligible channel. - **false**: **(Default)** Message deliveries aren't recorded. Enable post delivery audit logging ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| - **true**: An audit log entry is recorded each time | - System Config path: **Site Configuration > Content Flagging** | +| - **true**: An audit log entry is recorded each time | - System Config path: **Site Configuration > Data Spillage Handling** | | a message is delivered to a user. | - ``config.json`` setting: ``DeliveryTrackingSettings`` > ``Enable`` > ``false`` | | - **false**: **(Default)** Message deliveries aren't | - Environment variable: ``MM_DELIVERYTRACKINGSETTINGS_ENABLE`` | | recorded. | | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ -.. note:: +Delivery records are written to the audit log only, and aren't surfaced anywhere in the Mattermost interface. - Delivery records are written to the audit log only, and aren't surfaced anywhere in the Mattermost interface. They're discarded unless an audit log target consumes the ``audit-delivery`` log level. +.. warning:: + + Delivery records are discarded unless an audit log target consumes the ``audit-delivery`` log level. Setting this to **true** without configuring such a target records nothing, and Mattermost doesn't block the configuration. See :doc:`Post delivery audit logging `. .. config:setting:: delivery-tracking-all-channels - :displayname: Record deliveries in (Content flagging) - :systemconsole: Site Configuration > Content Flagging + :displayname: Record deliveries in (Data Spillage Handling) + :systemconsole: Site Configuration > Data Spillage Handling :configjson: .DeliveryTrackingSettings.EnableForAllChannels :environment: MM_DELIVERYTRACKINGSETTINGS_ENABLEFORALLCHANNELS :description: Record message deliveries in all eligible channels, or only in selected channels. Default is **true**. @@ -2303,7 +2305,7 @@ Record deliveries in ~~~~~~~~~~~~~~~~~~~~ +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| - **true**: **(Default)** Deliveries are recorded in | - System Config path: **Site Configuration > Content Flagging** | +| - **true**: **(Default)** Deliveries are recorded in | - System Config path: **Site Configuration > Data Spillage Handling** | | all eligible channels. | - ``config.json`` setting: ``DeliveryTrackingSettings`` > ``EnableForAllChannels`` > ``true`` | | - **false**: Deliveries are recorded only in the | - Environment variable: ``MM_DELIVERYTRACKINGSETTINGS_ENABLEFORALLCHANNELS`` | | selected channels. | | @@ -2311,11 +2313,11 @@ Record deliveries in .. note:: - Recording deliveries in all channels is the most complete option, and also the most expensive. Direct and group messages are never eligible, regardless of this setting. + Recording deliveries in all eligible channels is the most complete option, and also the most expensive. Direct and group messages are never eligible, regardless of this setting. .. config:setting:: delivery-tracking-channels - :displayname: Channels to record deliveries in (Content flagging) - :systemconsole: Site Configuration > Content Flagging + :displayname: Channels to record deliveries in (Data Spillage Handling) + :systemconsole: Site Configuration > Data Spillage Handling :configjson: N/A :environment: N/A :description: The channels in which message deliveries are recorded when deliveries aren't recorded in all channels. The list is stored in the database, so there's no ``config.json`` setting and no environment variable. Manage it in the System Console, or through the ``/api/v4/delivery_tracking/config`` API endpoints. @@ -2324,7 +2326,7 @@ Channels to record deliveries in ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ -| The channels in which message deliveries are | - System Config path: **Site Configuration > Content Flagging** | +| The channels in which message deliveries are | - System Config path: **Site Configuration > Data Spillage Handling** | | recorded. Applies only when **Record deliveries in** | - ``config.json`` setting: N/A | | is set to **Selected channels**, in which case at | - Environment variable: N/A | | least one channel is required. | | diff --git a/source/administration-guide/manage/admin/content-flagging.rst b/source/administration-guide/manage/admin/content-flagging.rst index bc97a3a6e67..fd6f9a1aae8 100644 --- a/source/administration-guide/manage/admin/content-flagging.rst +++ b/source/administration-guide/manage/admin/content-flagging.rst @@ -59,13 +59,13 @@ Configure - **Require reviewers to add comment**: Set to **True** to require reviewers to add a comment when resolving a quarantine. - **Hide message from channel while it is being reviewed**: Set to **True** to automatically hide quarantined messages from the channel until reviews are complete. If a root post is quarantined, the entire thread is hidden. -4. Under **Post Delivery Audit Logging**, record which users messages are delivered to: +4. Under **Post Delivery Audit Logging**, record each user, plugin, and outgoing webhook that a message is delivered to: - - **Enable post delivery audit logging**: Set to **True** to record an audit log entry each time a message is delivered to a user. These records are written to the audit log only, and aren't surfaced anywhere in the Mattermost interface. + - **Enable post delivery audit logging**: Set to **True** to record an audit log entry for each delivery of a message in an eligible channel. These records are written to the audit log only, and aren't surfaced anywhere in the Mattermost interface. - **Record deliveries in**: Select **All channels**, or select **Selected channels** to limit recording to specific channels. - **Channels to record deliveries in**: With **Selected channels** set, select the channels in which deliveries are recorded. - See :ref:`administration-guide/manage/admin/content-flagging:post delivery audit logging` for details. + Direct and group message channels are never eligible, regardless of **Record deliveries in**. See :ref:`administration-guide/manage/admin/content-flagging:post delivery audit logging` for details. .. tip:: We recommend enabling **Hide message from channel while it is being reviewed** and require comments from both reporters and reviewers to maintain transparency, accountability, and an auditable record of actions. @@ -199,7 +199,7 @@ When any step reports **Partial** or **Failed**, the report displays an *incompl Post delivery audit logging --------------------------- -From Mattermost v12.0, Mattermost can record an audit log entry each time a message is delivered to a user, so that you can establish which users a given message was delivered to. Delivery records add storage and processing cost, so enable them only where they're needed. +From Mattermost v12.0, Mattermost can record an audit log entry for each delivery of a message in an eligible channel, so that you can establish which users, plugins, and outgoing webhooks a given message was delivered to. Direct and group message channels are never eligible. Delivery records add storage and processing cost, so enable them only where they're needed. .. note:: @@ -207,15 +207,23 @@ From Mattermost v12.0, Mattermost can record an audit log entry each time a mess Delivery records are written to the audit log only. They aren't surfaced anywhere in the Mattermost interface, and they aren't included in any Mattermost report. To use them, ingest them with the same pipeline you use for the rest of your Mattermost audit log. +.. important:: + + Post delivery audit logging requires the `feature flag `_ ``MM_FEATUREFLAGS_POSTDELIVERYTRACKING``, which is disabled by default, and a server restart after you enable it. + +.. warning:: + + Delivery records are discarded unless an audit log target consumes the ``audit-delivery`` log level. Enabling the setting without configuring such a target records nothing, and Mattermost doesn't block the configuration. Configure the target first. + To enable post delivery audit logging: -1. Add an audit log target that consumes the ``audit-delivery`` log level. Delivery records are discarded until a target consumes them, so do this first. See :doc:`Post delivery audit logging `. +1. Add an audit log target that consumes the ``audit-delivery`` log level. See :doc:`Post delivery audit logging `. 2. Go to **System Console > Site Configuration > Data Spillage Handling**, and find **Post Delivery Audit Logging**. 3. Set **Enable post delivery audit logging** to **True**. 4. Set **Record deliveries in**: - **All channels**: Deliveries are recorded in every eligible channel. This is the most complete option, and the most expensive. - - **Selected channels**: Deliveries are recorded only in the channels you select. At least one channel is required. + - **Selected channels**: Deliveries are recorded only in the eligible channels you select. At least one channel is required. 5. With **Selected channels** set, use **Channels to record deliveries in** to select the channels. Direct and group message channels can't be selected. Recording starts when you save, and applies to messages sent from then on. diff --git a/source/administration-guide/manage/logging.rst b/source/administration-guide/manage/logging.rst index 5d5a04f37f2..ba45e280b92 100644 --- a/source/administration-guide/manage/logging.rst +++ b/source/administration-guide/manage/logging.rst @@ -214,7 +214,7 @@ Audit logging By default, Mattermost doesn't write audit logs locally to a file on the server, and the ability to enable audit logging in Mattermost is currently in :ref:`Beta `. -You can enable and customize advanced audit logging in Mattermost to record activities and events performed within Mattermost, such as user access to the Mattermost REST API or mmctl. Audit logs are recorded asynchronously to reduce latency to the caller, and are stored separately from general logging. During short spans of inability to write to targets, the audit records buffer in memory with a configurable maximum record cap. Based on typical audit record volumes, it could take many minutes to fill the buffer. After that, the records are dropped, and the record drop event is logged. From Mattermost v12.0, the default maximum number of buffered audit records is 10,000, increased from 1,000. +You can enable and customize advanced audit logging in Mattermost to record activities and events performed within Mattermost, such as user access to the Mattermost REST API or mmctl. Audit logs are recorded asynchronously to reduce latency to the caller, and are stored separately from general logging. During short spans of inability to write to targets, the audit records buffer in memory with a configurable maximum record cap. Based on typical audit record volumes, it could take many minutes to fill the buffer. After that, the records are dropped, and the record drop event is logged. From Mattermost v12.0, this shared audit queue holds up to 10,000 records, increased from 1,000. It's separate from the per-target ``maxqueuesize`` option, which caps the queue of an individual output target and is unchanged. .. note:: @@ -692,14 +692,15 @@ The following log levels support audit logs: +--------+-----------------------+------------------------------------------------------------------------+ | 103 | ``audit-cli`` | CLI operations | +--------+-----------------------+------------------------------------------------------------------------+ -| 104 | ``audit-delivery`` | Deliveries of message content to users and integrations. Available | -| | | from Mattermost v12.0. This log level generates considerably more | -| | | records than any other audit log level. | +| 104 | ``audit-delivery`` | Deliveries of message content to users, plugins, and outgoing | +| | | webhooks in eligible channels. Direct and group message channels are | +| | | never eligible. Available from Mattermost v12.0. This log level | +| | | generates considerably more records than any other audit log level. | +--------+-----------------------+------------------------------------------------------------------------+ -.. note:: +.. warning:: - The ``audit-delivery`` log level isn't written by the built-in audit log file target, so enabling ``ExperimentalAuditSettings.FileEnabled`` doesn't capture delivery records. To capture them, add a target for the level to ``ExperimentalAuditSettings.AdvancedLoggingJSON``. See :doc:`Post delivery audit logging `. + The ``audit-delivery`` log level isn't written by the built-in audit log file target, so enabling ``ExperimentalAuditSettings.FileEnabled`` doesn't capture delivery records — they're discarded. To capture them, add a target whose ``levels`` list includes ``{"id": 104, "name": "audit-delivery"}`` to ``ExperimentalAuditSettings.AdvancedLoggingJSON``. See :doc:`Post delivery audit logging `. The following log levels support application logs: From 3a075a84ae0d7eeb3b3bbb1c4b23234039844fd8 Mon Sep 17 00:00:00 2001 From: Harshil Sharma Date: Tue, 18 Aug 2026 09:02:01 +0530 Subject: [PATCH 5/6] Updated a statement for channel filtering to make it clearer --- source/administration-guide/manage/admin/content-flagging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/administration-guide/manage/admin/content-flagging.rst b/source/administration-guide/manage/admin/content-flagging.rst index fd6f9a1aae8..7809cfee796 100644 --- a/source/administration-guide/manage/admin/content-flagging.rst +++ b/source/administration-guide/manage/admin/content-flagging.rst @@ -225,7 +225,7 @@ To enable post delivery audit logging: - **All channels**: Deliveries are recorded in every eligible channel. This is the most complete option, and the most expensive. - **Selected channels**: Deliveries are recorded only in the eligible channels you select. At least one channel is required. -5. With **Selected channels** set, use **Channels to record deliveries in** to select the channels. Direct and group message channels can't be selected. Recording starts when you save, and applies to messages sent from then on. +5. With **Selected channels** set, use **Channels to record deliveries in** to select the channels. Direct and group message channels can't be selected. Recording starts when you save and applies to eligible message content delivered from then on, including existing messages delivered through later channel loads, searches, and fetches. **Enable post delivery audit logging** and **Record deliveries in** can also be configured via the :ref:`config.json file or through environment variables `. From 71d11940775e55082f46a94db3bd51c972384445 Mon Sep 17 00:00:00 2001 From: Harshil Sharma Date: Wed, 26 Aug 2026 09:41:36 +0530 Subject: [PATCH 6/6] Clarified avbout advanced logging --- .../comply/post-delivery-audit-logging.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/administration-guide/comply/post-delivery-audit-logging.rst b/source/administration-guide/comply/post-delivery-audit-logging.rst index 443936ec833..66720c1fded 100644 --- a/source/administration-guide/comply/post-delivery-audit-logging.rst +++ b/source/administration-guide/comply/post-delivery-audit-logging.rst @@ -19,7 +19,8 @@ Post delivery audit logging requires all of the following: - A Mattermost Enterprise Advanced license. - The `feature flag `_ ``MM_FEATUREFLAGS_POSTDELIVERYTRACKING``, which is disabled by default. **Restart the server after enabling the feature flag**. -- An audit log target that consumes the ``audit-delivery`` log level. +- Advanced Logging > Advanced Logging to be enabled +- An audit log target that consumes the ``audit-delivery`` log level in the advanced audit log config. .. important::