Skills, tools & MCP

Three building blocks you attach to an agent. For ready-made examples, see the SAMPLES.md in the repo's docs/ folder.

Two more things an agent can call are documented on their own pages, because Relay executes them too: workflows attached as tools, and the read-only Microsoft 365 connector tools; a dataset agent's SQL tool is gateway-owned as well.

#Skills

A skill is shared prompt text — tone, formatting rules, house style, domain facts — that many agents reuse without duplicating it. Attach several to an agent and their instructions are concatenated into the composed system prompt (before the agent's own prompt). Manage them under Skills; fetch/attach programmatically via the control-plane api/Skills.

#Tools

A tool is a function definition: a name, a description, and a JSON-Schema parameters object. Attaching a tool advertises it to the model.

Execution model — important:

• A registry tool with no backend of its own is only advertised. When the model calls it, Relay returns the tool_calls to your app to execute, and the run ends there (your app sends the result back as a tool message on its next call).
• A tool whose name is served by an attached MCP server, an attached workflow (workflow_<slug>), a connector (microsoft_*) or a dataset (relay_run_dataset_sql) is executed by Relay automatically inside the agent's tool loop. A registry tool whose name collides with one of those fails the run with 409 tool_name_conflict.

So: use MCP servers (or workflows) when you want Relay to run the tool; use registry tools when your app runs it. Read the registry with GET /v1/tools.

#The parameters schema

Paste the parameters object on its own — { "type": "object", "properties": { … }, "required": [ … ] } — not the whole function definition wrapped around it. Leave the field empty for a tool that takes no arguments.

Trailing commas and // comments are accepted and tidied away on save, since a schema is usually hand-written or lifted out of source. What gets stored is always strict JSON, because the gateway re-parses it with default options when it advertises the tool. Anything that cannot serve as a function's parameters is refused while you are still looking at the form — a top level that is not an object, a type other than "object", a non-object properties, or a required that is not a list of names — rather than by the provider partway through a conversation. Syntax errors are reported with the line and character, and typographic quotes (“ ”) pasted in from a document are called out by name, because the parser's own complaint about them is unrecognisable.

#MCP servers

Register a Model Context Protocol server by URL (HTTP/SSE JSON-RPC) with an optional bearer token, sent as Authorization: Bearer …. Click Discover tools to run tools/list and cache the server's tools for attachment. When such a server is attached to an agent, the agent run enters a tool loop: call the model → execute each requested MCP tool (tools/call, 20-second timeout) → feed results back → repeat, up to Gateway:ToolMaxIterations (default 5). A failed call never aborts the run: it comes back to the model as [tool error] … text it can react to. Dataset and connector agents use their own budgets (Gateway:Data:MaxIterations, 6; Gateway:Connectors:MaxIterations, 8).

The Tools count in the list is a link: click it to see what the server actually exposes — each tool's name and description, its arguments with type and required marker, and the raw inputSchema behind a disclosure. It reads the cached copy, so it shows what Relay will advertise to the model, which is only as fresh as the last discovery run.

Transport is HTTP/SSE — local stdio MCP servers aren't reachable from a hosted gateway; front them with an HTTP/SSE bridge. Discovery sends a bare tools/list without an initialize handshake or session, so a server that insists on one fails discovery and shows sync error on the MCP page.

MCP bearer tokens are stored as entered, not encrypted — unlike provider keys, connector tokens and workflow credentials. MCP tools are also not executed in realtime sessions.

#Putting it together

A typical support agent: skills Concise tone + Bilingual; tools get_order_status, create_support_ticket (your app executes them); MCP server Docs MCP (Relay executes it); workflow Escalate to Jira attached as a tool (Relay runs it). See the samples file for concrete definitions.