Binions can present your automations to an AI assistant as callable tools. The Model Context Protocol (MCP) is the standard way for AI agents — coding assistants, chat copilots, in-house bots — to discover and call external tools. Binions exposes a built-in MCP server, so an agent can list your playbooks and run them, getting structured results back. Each tool is just a playbook you already have; you decide which ones to publish.
Safe by default. The MCP endpoint exposes nothing until you explicitly list the tools you want to publish. An AI agent can only call the playbooks you have named — never arbitrary actions — and every call runs through the same playbook engine, with the same guard rails, as any other workflow.
| What it does | Lets an AI agent discover and call selected playbooks as tools |
| Served by | The showman daemon, at POST /mcp on the HTTP edge |
| Protocol | Model Context Protocol over JSON-RPC (initialize, tools/list, tools/call) |
| A tool is | A named entry in config that maps to a playbook — no new code, no new vocabulary |
| Default | Enabled, but with an empty tool list — exposes nothing until you add tools |
| Behind | The Basic-Auth’d edge entry point, like the rest of the inbound surface |
An MCP-capable client (for example a coding assistant) connects to /mcp, asks what tools are available, and calls one with arguments. Behind the scenes a tool call is an ordinary platform event:
Why this is useful. It turns Binions into an action layer for AI: an assistant can “check the order count”, “provision a tenant”, or “run the nightly report” by calling a tool, and each tool is a playbook you have reviewed and control — not an open door to your systems.
An MCP client — a coding assistant, an IDE plug-in, or your own script — talks to the server over HTTP with JSON-RPC. The /mcp endpoint sits behind the platform’s authenticated edge, so a client presents credentials, lists the tools, and calls one. The credential is never discoverable over the network: an operator reads it from the host once and hands it to the client.
Finding the host is not the same as getting in. A client that reaches the endpoint without valid credentials is refused, and repeated wrong attempts are locked out for a while. There is no way to guess or auto-discover the key — you provision it deliberately, out of band.
The credential is generated when the package is installed and kept as a single line in showman’s secrets directory. Read it on the host and pass it to whoever configures the client — never commit it to a repository:
sudo cat /opt/binions/showman-service/secrets/mcp-deploy.credential
# one line, of the form user:password| From another machine | https://YOUR_HOST:8446/mcp — the authenticated HTTPS edge |
| On the host itself | http://127.0.0.1:9099/mcp — the local endpoint |
| Authentication | HTTP Basic, using the user:password from step 1 |
List what the server offers, then call a tool by name with a small JSON object of arguments:
CRED='user:password' # the line from step 1
# list the available tools
curl -u "$CRED" -H 'Content-Type: application/json' \
-X POST https://YOUR_HOST:8446/mcp \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# call a tool by name
curl -u "$CRED" -H 'Content-Type: application/json' \
-X POST https://YOUR_HOST:8446/mcp \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"TOOL_NAME","arguments":{}}}'A native MCP client — such as a coding assistant or IDE — is set up the same way: register an HTTP server with the endpoint URL and an Authorization: Basic header carrying the same credential. By default the edge serves a self-signed certificate, so point the client at a trusted certificate or tell it to trust this one. An empty tool list simply means nothing has been published yet for the credential you presented.
Two pieces make a tool: a config entry that names it, and a playbook that does the work. The config entry maps the tool to a route; the playbook triggers on that route.
First, declare the tool in showman’s configuration. Give it a name and description the agent will see, the route it dispatches to, and an optional schema for its arguments:
# showman application.toml
[mcp]
enabled = true
[[mcp.tools]]
name = "orders-count"
description = "Count the rows in a registered table. Arguments: { table: string }."
route = "mcp-orders-count"
input_schema = { type = "object", properties = { table = { type = "string" } }, required = ["table"] }
Then write the playbook that implements it. It triggers on the tool’s route, does its work with ordinary verbs, and replies — the reply becomes the tool result:
name: mcp-tool-orders-count
on:
event: Fact.Http.Received
filter: { route.eq: mcp-orders-count }
steps:
- run: database.count
id: c
with:
table: ${trigger.body.table}
- run: webhook.send # the reply becomes the tool result
with:
url: "http://127.0.0.1:9099/in/_reply/${trigger.correlation_id}"
body: { count: ${steps.c.count} }
An agent that lists tools now sees orders-count, and calling it with { "table": "orders" } returns the count. Add as many tools as you like; each is one config entry plus one playbook.
Publishing tools lets an agent call the playbooks you chose. The MCP server can also offer a small, fixed set of built-in tools for managing automations — so an assistant can draft a playbook, install it, and reuse it, without anyone editing files on the host. This is optional and switched off until you turn it on.
| Built-in tool | What it does |
|---|---|
deploy-playbook | Validate a playbook written in YAML and install it live in a dedicated namespace, hot-reloaded at once — no restart. |
list-playbooks | List the playbooks deployed this way, with each one’s trigger event and when it last changed. |
remove-playbook | Remove a previously deployed playbook and hot-reload. |
Turn the feature on with a single switch. Playbooks deployed this way land in their own namespace, kept apart from the ones you ship with the host, so an agent can iterate freely without ever overwriting your own work:
# showman application.toml
[mcp.deploy]
enabled = trueGuarded deployment. The deploy tools sit behind their own dedicated key, separate from any operator login, and stay invisible to an agent that does not present it. Repeated wrong keys lock the tools out for a while, and every submitted playbook is checked against a deny-list before it is accepted — it cannot read your secrets, open SSH sessions, or reach outside the host. An agent can build automations, but only inside a safe boundary.
[[mcp.tools]] exist. There is no generic “run any action” tool — an agent is confined to the playbooks you published./mcp sits behind the same authenticated HTTP edge entry point as the rest of the inbound surface, so it is not open to the public internet by default.