Tools and MCP

Tools let the agent do things: look up an order, book a slot, create a ticket. There are four kinds:

Kind	Runs	Set up in
Built-in	On the server	The bot's Tools tab (tools.builtins)
HTTP tools	On the server, calling your API	Tools in the admin panel, then picked per bot
MCP servers	On the server, through the Model Context Protocol	Tools in the admin panel, then picked per bot
Page tools	In the visitor's browser	Your page: see Client tools

Every call is checked against the tool's JSON Schema first, limited by tools.toolTimeoutMs (15 seconds by default), and recorded with the conversation (your team sees tool calls in the transcript). Results from HTTP, MCP and page tools are cut to tools.maxResultChars (8,000 characters) and marked as untrusted information, so a response that contains instructions can't take over the agent.

Built-in tools

Tool	Available when	What it does
search_knowledge	The bot has knowledge sources (and knowledge.mode isn't auto, or in voice)	Searches the knowledge base.
capture_lead	behavior.leadCapture.enabled	Saves the visitor's contact details, with the bot's lead fields.
handoff_to_human	behavior.handoff.enabled	Asks a person from your team to take over. See Human handoff.
end_conversation	Always	Ends the conversation after the agent's goodbye.
look_at_camera	vision.webcam.enabled	Looks through the visitor's camera. See Vision.
express	Voice	Changes the face's expression, silently. (Text replies use mood tags instead.)

Turn any of them off under tools.builtins.

HTTP tools

An HTTP tool is a request to your own API that the agent can make. Define it once under Tools, then turn it on for the bots that should use it (tools.http).

Field
Name	What the agent calls it: lowercase letters, digits and _, starting with a letter. Not a built-in tool's name.
Label	A friendlier name, used when the chat asks the visitor first.
Description	What it does and when to use it (up to 2,000 characters).
Parameters	A JSON Schema for the arguments the agent must give.
Request	Method (GET, POST, PUT, PATCH, DELETE), URL, headers, query parameters and body, with placeholders.
Response pick	A dotted path into a JSON response (data.items.0) to give the agent only that part.
Timeout	1 to 60 seconds (10 by default).
Ask the visitor first	Shows a question in the chat before each call (see below).
Allow private network	Lets this tool reach private addresses (see below).

The admin panel can run a tool with sample arguments to check it.

Placeholders

The URL, headers, query parameters and body can contain placeholders:

Placeholder	Value
{{args.NAME}}	An argument from the agent; dotted paths reach into objects ({{args.address.city}})
{{secret.NAME}}	A stored secret (below)
{{visitor.id}}	The visitor's id
{{visitor.userId}}	Your user id, only for a verified visitor (otherwise empty)
{{visitor.email}}	Their email, only for a verified visitor (otherwise empty)
{{visitor.name}}	Their name, from identity or a lead form (not verified)
{{visitor.verified}}	true when your website signed the visitor's identity, otherwise false
{{conversation.id}}	The conversation's id

Values are written safely for where they go: URL-encoded in the URL, as JSON string content in a JSON body (a body starting with { or [), with line breaks removed in headers. A missing value is written as nothing. Objects and arrays are written as JSON.

POST https://api.example.com/orders/{{args.order_id}}/refund
Authorization: Bearer {{secret.SHOP_API_KEY}}
Content-Type: application/json

{ "reason": "{{args.reason}}", "customer": "{{visitor.userId}}" }

With no body template, POST, PUT and PATCH send the agent's arguments as JSON. GET and DELETE send no body.

The response goes to the agent as text: JSON (after the response pick), the readable text of an HTML page, or the body as it is. Up to 1 MB is read, and up to 3 redirects are followed. A 4xx or 5xx status is reported to the agent as an error with the start of the body.

Identity in tools

{{visitor.userId}} and {{visitor.email}} are filled in only when your website signed the visitor's identity, so a visitor can't make a tool act for someone else's account. {{visitor.name}} is whatever the visitor or page said. If the agent passes an email as an argument (from a lead form, say), treat it as unverified. See Identity verification.

Secrets

Secrets hold API keys and tokens for HTTP tools. Add them under Tools with an UPPER_CASE name; use them as {{secret.NAME}}. Values are encrypted at rest and never shown again, and the agent never sees them: they are filled in only when the request is sent.

MCP servers

Connect any Model Context Protocol server under Tools. The server lists its tools straight away; turn the server on for a bot (tools.mcp) and choose which of its tools the bot may use (* for all).

Transport
streamable_http	A URL. If the server doesn't speak Streamable HTTP, the older SSE transport is tried.
sse	A URL, using the SSE transport.
stdio	A command (and arguments) the Wireface server runs as a child process. Off unless the server sets ALLOW_STDIO_MCP=true.

• Headers (for example Authorization) and environment variables for stdio servers are encrypted at rest, and never shown again: editing replaces them unless you keep them.
• Tools appear to the agent as mcp_<server>_<tool> (the server's name in lowercase letters, digits and _), with the server's description of each.
• Results can be text, images (up to three are kept with the conversation, and the agent sees them), resources and structured content.
• Refresh lists the server's tools again after it changes.
• Connections are kept open and closed after 30 minutes unused.

stdio servers run on your machine

A stdio MCP server runs a command on the Wireface server. It gets a minimal environment (PATH, HOME and the like) plus the variables you set for it, never the server's own keys and settings; but the command itself can do anything the server's user can. Only allow ALLOW_STDIO_MCP where everyone with admin access is trusted with a shell on that machine.

Tools that ask first

Some actions need the visitor's yes. Three kinds of tool pause before running:

• HTTP tools with Ask the visitor first on;
• MCP tools the server marks as destructive (destructiveHint: true), when the bot's link to that server has confirmDestructive on (the default);
• page tools registered with confirm (see Client tools).

The chat shows the question, "Ava wants to: refund order. Is that OK?" (the tool's label, or its name), with the arguments and Allow / Don't allow buttons, in every tab the visitor has open; the first answer counts. If they say no, or don't answer within 2 minutes, the tool doesn't run and the agent is told the visitor declined, so it can ask what they'd like instead. If nobody has the chat open, the tool doesn't run.

Private addresses (SSRF protection)

Tool requests, MCP connections, webhooks and the knowledge crawler can only reach the public internet. The server refuses localhost and private, loopback, link-local (including cloud metadata at 169.254.169.254), carrier-NAT, multicast and reserved addresses, checking the address a name actually resolves to when it connects (so a DNS name pointing inside your network is refused too). Only http and https URLs are allowed.

To call an API on your own network, turn on Allow private network for that HTTP tool, or set ALLOW_PRIVATE_NETWORK=true on the server (which applies to MCP servers, webhooks and the crawler as well).