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.
| Block | What it is | How the agent uses it |
|---|---|---|
| Skill | A reusable instruction block (tone, rules, domain knowledge). | Its instructions are folded into the system prompt. |
| Tool | An OpenAI-style function definition (name + description + JSON-Schema params). | Advertised to the model so it can request a call. |
| MCP server | A Model Context Protocol server discovered over JSON-RPC. | Its tools are advertised and executed by Relay's tool loop. |
#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 MCP backend is only advertised. When the model calls it, Relay returns the
tool_callsto your app to execute. - A tool whose name is served by an attached MCP server is executed by Relay automatically inside the agent's tool loop.
So: use MCP servers 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. 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 → feed results back → repeat, up to Gateway:ToolMaxIterations (default 5).
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
stdioMCP servers aren't reachable from a hosted gateway; front them with an HTTP/SSE bridge.
#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). See the samples file for concrete definitions.