External agents (MCP)

Viaducta has an MCP (Model Context Protocol) endpoint, so AI agents outside the designer can work with your flows: Claude Code, or any other MCP client. An agent can hand a task to the Viaducta assistant, or use the same tools the assistant uses, directly. Every agent signs in as a Viaducta user and works under that user's roles and the approval rules below.

Enable the endpoint

The endpoint is off until the administrator turns it on in the Manager's configuration:

"ExternalAccess": {
  "Enabled": true,
  "PublicBaseUrl": "https://viaducta.example.com/api"
}

Agents then connect to {PublicBaseUrl}/mcp. Sign-in uses OAuth through your Keycloak: the endpoint publishes its authorisation server at /.well-known/oauth-protected-resource, and agents sign in with the Keycloak client viaducta-mcp, which you create in the Viaducta realm. Behind a reverse proxy, route /api/mcp and /.well-known/ to the Manager.

Key	Default	Meaning
Enabled	false	Turns the endpoint on.
PublicBaseUrl		The address agents use, without /mcp.
AllowedClients	viaducta-mcp, viaducta-mcp-ci	Keycloak clients whose tokens are accepted.
AllowedOrigins	none	Browser origins allowed to call the endpoint. Command-line agents send no origin and are always allowed.
CallsPerMinute	120	Calls per user and minute.
DirectToolApproval	production	always: outside production too, running and deleting wait for approval in the designer.
DirectToolsMaxRisk	destructive	The highest risk an agent may use directly: read, edit, execute or destructive. Tools above it are not offered.
MaxRunningConversations	2	Tasks handed to the assistant that run at the same time, per user.
MaxTurnMinutes	60	Longest run of one handed-over task.

Designers and administrators may use external agents. Every call is recorded in the log.

Connect Claude Code

Install the Viaducta plugin for Claude Code. It adds the MCP connection, a viaducta skill that tells Claude how to work with Viaducta, and a viaducta-builder agent that hands flow work to the assistant and follows it to the end.

claude plugin marketplace add <path or Git URL of the plugin>
claude plugin install viaducta@viaducta

1. Set the plugin's Viaducta URL (/plugin → manage → viaducta → configure), for example https://viaducta.example.com/api, and restart Claude Code.
2. Run /mcp, choose the Viaducta server and Authenticate. Your browser opens the Viaducta sign-in page.
3. In the designer, open Viaducta AI and switch on the robot button in its toolbar to let external agents use that designer tab. Tools that act in the designer, such as opening a flow, run in the tab you allowed most recently.

Without the plugin, add the server directly:

claude mcp add --transport http --client-id viaducta-mcp --callback-port 33418 viaducta https://viaducta.example.com/api/mcp

With a self-signed certificate, make Node trust it with NODE_EXTRA_CA_CERTS.

What an agent can do

• ViaductaConnection shows the signed-in user, tenant, environment, whether a designer tab is available, and the approval rules.
• Hand over a task. ViaductaAgent gives a task to the Viaducta assistant, in Agent, Plan or Ask mode, optionally with a flow and up to 20 text files. ViaductaAgentStatus follows it, ViaductaAgentAnswer answers the assistant's questions, ViaductaAgentStop stops it and ViaductaAgentConversations lists earlier tasks. The conversations also appear in the designer's chat list, so you can watch them. These tools need the assistant to be on.
• Use the tools directly. The assistant's own tools - reading and changing flows, types, scripts, running and debugging, logs, alarms, the repository - are offered to the agent, up to DirectToolsMaxRisk.
• Prompts build-flow, fix-flow and explain-flow, and the Viaducta guides as MCP resources.

Approvals

• Reading never asks.
• In production every change waits for approval in the designer, on the same Approval needed card the assistant uses. Approvals for external agents are given one by one; Always allow is not offered. An unanswered request expires after ten minutes.
• Outside production, changes follow the agent's own permission prompt (for example Claude Code's), unless DirectToolApproval is always.
• Tasks handed to the assistant follow its normal approval rules in the designer.