The assistant and MCP
Copy page
This page explains the two ways an AI model works with Sluice. The assistant is a chat panel in the web UI. The MCP server at /mcp gives the same tools to an external client, for example a coding agent. Both use one tool registry, so a tool behaves the same in both places.
One tool registry
Section titled “One tool registry”Each tool has a name, an input schema, a minimum role and a mutating flag. MCP tools lists all of them.
| Group | Tools | Minimum role |
|---|---|---|
| Read | list_namespaces, list_flows, get_flow, list_files, read_file, validate_flow, get_flow_schema |
viewer |
| Read executions | list_executions, get_execution, get_logs, get_metrics, get_insight |
viewer |
| Run | trigger_execution, cancel_execution, rerun_execution, restart_execution, resume_execution, reject_execution |
operator |
| Change files | propose_change, apply_change |
editor |
A tool is mutating when it changes Sluice: the run tools and apply_change. propose_change validates files and returns a diff, but it writes nothing. Only the assistant has propose_change. An MCP client uses validate_flow and then apply_change.
The assistant also has fetch_url when an admin turns on web access. See Web access. MCP does not serve it, because an MCP client has its own web access.
A tool call always checks the role of the caller. A caller without the role gets the tool error forbidden. The assistant offers the model only the tools that your role allows.
Two front ends
Section titled “Two front ends”| Assistant | MCP server | |
|---|---|---|
| Where | The Assistant panel on every page of the web UI. | /mcp, streamable HTTP, stateless, JSON answers. |
| Who calls the model | Sluice, with the configured AI provider. | The client, with its own model. Sluice needs no provider. |
| Credential | Your session. | An API token. A session cookie gets 401. |
| Role | Your role. | The effective role of the token. |
| Mutating tools | Wait for your Confirm, unless Accept all is on. | Run at once. |
| Audit | ai.action.confirmed, ai.action.rejected or ai.action.auto_confirmed, and the event of the change itself. |
ai.tool.call, and the event of the change itself. |
/.well-known/mcp.json describes the MCP server for discovery. It names the endpoint and the Authorization header, and holds no data.
Confirm before a change
Section titled “Confirm before a change”The assistant never changes Sluice on its own. When the model calls a mutating tool, the call does not run. The panel shows it with Confirm and Reject:
- Confirm runs the tool as you, with your role. The change has you as its actor.
- Reject tells the model that you refused. The model continues the turn with this fact.
- While an action waits, you cannot send a new message.
Accept all
Section titled “Accept all”The Accept all switch in the panel header applies to one conversation. It is off in a new conversation. When it is on, a mutating call runs at once, as you and with your role. The tool card shows Auto-accepted, and the audit log records ai.action.auto_confirmed.
Accept all stops for the rest of a turn after a fetch_url call. Sluice does not trust the text of a web page, so a page must not start an action without a person. The mutating calls after the fetch wait for Confirm.
An MCP client has no such step. Sluice cannot ask a person inside an MCP call, so a mutating tool runs when the client calls it. The client can ask its own user first. Control an MCP client with its token: give it the lowest role that it needs, and an expiry. A viewer token gets only the read tools.
Web access
Section titled “Web access”An admin turns on Web access on Settings → AI provider. The assistant then has the tool fetch_url, which reads one web page as text.
- It sends GET over
httporhttps. It follows at most 5 redirects and stops after 10 seconds. - It refuses loopback, private, link-local, carrier-grade NAT and cloud metadata addresses. Sluice checks the address after the DNS lookup, also on each redirect.
- It reads text, HTML, JSON and XML. It converts HTML to text, and returns at most 100 000 characters.
- Allowed domains limits the hosts. A domain allows its subdomains. An empty list allows every public domain.
fetch_url has no web search. The model can fetch a search page or a documentation URL that it knows.
Masking
Section titled “Masking”Execution data can hold secret values, for example in a log line. The tools get_execution, get_logs, get_metrics and get_insight mask their results with the secret values of every task run of the execution. A secret shows as ***. The grep of get_logs searches the masked text, so a secret value never matches.
The same masking applies to the triage context and to attachments. No model request and no MCP result holds a secret value that Sluice knows.
Attachments
Section titled “Attachments”In the assistant, type @ to attach a flow, a recent execution or a namespace file to a message. A message holds at most 5 attachments. Sluice reads each attachment with the read tools, as you. Your role, the masking and the size limit of the tools thus apply. A message with an object that you cannot read fails.
| Attachment | Content for the model |
|---|---|
| Flow | get_flow: the flow with its YAML source. |
| File | read_file: the file of the head version of the namespace. |
| Execution | get_execution, get_insight, and get_logs with failed_only and the last 100 lines. |
Fix with assistant on a failed execution starts a new conversation with the execution attached. See Triage a failed execution.
Flow authoring
Section titled “Flow authoring”When you ask the assistant for a flow change, it calls propose_change. The panel shows the diff of each file and the validation issues. When the proposal is invalid, the model gets the issues and can try again. When it is valid, the model calls apply_change, and you confirm.
| Namespace source | Result of apply_change |
|---|---|
| Managed | A new version of the namespace. |
| Git | A new branch sluice/<user>/<time> from the last synced commit. The tracked branch does not change. |
apply_change refuses a change with an invalid flow, also over MCP.
Failure triage
Section titled “Failure triage”A triage explains why an execution failed. It has a summary, a probable cause, evidence log lines, a suggested fix and a confidence of low, medium or high. Sluice stores it as an insight of the execution.
An operator requests a triage with Triage on a FAILED or TIMED_OUT execution. With automatic triage on, Sluice queues one when such an execution ends. Every instance takes queued triages. A triage has 3 minutes. A running triage older than 15 minutes, for example of a stopped instance, becomes failed.
The model gets this context, all of it masked:
- the flow source and the spec of the failed task;
- the error, the exit code, the outputs and the metrics of the execution;
- the first 50 and the last 400 log lines of the failed attempt;
- the file diff against the last successful execution of the flow, at most 200 lines;
- the durations of the last 10 executions of the flow.
SLUICE_AI_MAX_CONTEXT_CHARS limits the context, 120 000 characters by default. The facts, the flow source and the diff get at most half of the limit. The log lines get the rest, a quarter for the first lines and the remainder for the last lines. A cut shows as …(N lines omitted).
The model must quote evidence lines exactly. Sluice removes an evidence line whose text is not in a log line of the failed task, and it corrects the line number. The evidence that you see is thus always a real log line.
Limits
Section titled “Limits”| Limit | Value | Result |
|---|---|---|
| Model answers with tool calls in one assistant turn | 20 | The turn stops with step_limit_reached. |
| Invalid proposals in one turn | 3 | propose_change answers retry_limit_reached. |
| Tool result for the model | 20 000 bytes, 100 000 characters for fetch_url |
Sluice cuts the rest. |
| One message | 20 000 characters | Validation error. |
| Attachments of one message | 5 | The panel does not add more. |
Rows of list_executions |
50 | |
Lines of get_logs |
1 to 1 000, default 200 | |
| Triage context | SLUICE_AI_MAX_CONTEXT_CHARS |
Sluice cuts log lines first. |
A provider answer of 429 or 5xx, or a network error, gets 3 attempts in total.
Conversations
Section titled “Conversations”The assistant keeps your conversations in Postgres. Other users do not see them. A conversation holds the messages, the tool calls and the actions that wait or that you confirmed or rejected.
A turn is one run of the assistant, from your message or a decision on an action until the answer ends. It runs on the server, not in the browser:
- A reload, a closed tab or a second tab does not stop it. The panel attaches to the running turn and shows the text as it streams.
- Stop ends a running turn. The text so far stays as the answer, marked Stopped.
- A turn that fails, for example after 3 provider errors, shows the error and Retry. Retry runs the turn again from the saved messages, without a second copy of your message.
- When the instance of a turn stops, the turn fails after 60 seconds without a heartbeat. You can then retry it.
- One turn runs at a time in a conversation. A second message gets
409 turn_running.
Each message has a copy button for its text, and each tool card has one for its arguments.
The API starts a turn with POST /api/v1/ai/conversations/{id}/messages and answers 202. GET /api/v1/ai/conversations/{id}/events streams the conversation each time it changes, until the turn ends. POST .../stop and POST .../retry stop and retry a turn.