---
id: ai-external-agents
title: "External agents (MCP)"
summary: "Let AI agents such as Claude Code work with Viaducta through its MCP endpoint - enable ExternalAccess, sign in through Keycloak, install the Claude Code plugin, and the tools and approval rules agents work under."
audience: user
keywords: "mcp, model context protocol, external agents, claude code, plugin, ExternalAccess, oauth, keycloak, viaducta-mcp, ViaductaAgent, approval"
---
# 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:

```json
"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.

```bash
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:

```bash
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.