Connector files

A connector: one HTTP endpoint, described once. Its method and URL, its parameters, the shape of its request and response, and the kind of credential it needs. Agents never call a connector directly: a tool points at it.

What connectors are for, and how to use them: Tools.

Where the file goes

connectors/open-api/, or any sub-folder of it. The file name without .mtr is the connector’s name. Other files refer to it as @ref("<name>").

A resource’s name is its file name without .mtr (an app’s is its folder’s name). Use letters, digits, _, - and . (but not ..), at most 128 characters. Two files of the same kind may not have the same name, even in different sub-folders or with different capitals.

Properties

A file must set method, url and description. Everything else is optional.

method

Required. HTTP method.

The HTTP method.

Usually one of GET, POST, PUT, PATCH, DELETE.

method = "GET"

url

Required. URL.

The endpoint’s full URL. {name} in it marks a path parameter, declared in parameters.path.

url = "https://api.open-meteo.com/v1/forecast"

description

Required. Text.

What the endpoint does, in a sentence (500 characters at most).

description = "Current weather for a latitude and longitude, from Open-Meteo"

parameters.path

Optional. List of blocks.

The parameters in the URL’s path, one for each {name} in url.

parameters.query

Optional. List of blocks.

The query-string parameters.

schema.request

Optional. JSON text.

The JSON Schema of the request body, usually @json("name"). The model’s arguments are checked against it before the call is made. Without one, no body is sent, even for a POST.

schema.request = @json("refund-request")

schema.response

Optional. JSON text.

The JSON Schema the endpoint’s response must match, usually @json("name").

schema.response = @json("order")

postProcessResponseUnicodeCharacters

Optional. true or false. Default: false.

Replace typographic characters in the response (curly quotes, dashes, bullets, the ellipsis) with plain ones before it is read. Applies when schema.response is set.

postProcessResponseUnicodeCharacters = true

auth

Optional. One of the values below. Default: "None".

The kind of credential the endpoint needs. The credential itself is given where a tool uses the connector.

Value	Meaning
None	No credential is sent.
Header	A secret’s value, sent in an HTTP header that the tool names.
Maitento	A short-lived Maitento token, for connectors that call Maitento’s own API.

auth = "Header"

Each item of parameters.path

A path or query parameter of a connector: { name = "latitude" description = "Latitude in decimal degrees" type = "number" }.

The same block is used for parameters.query.

parameters.path › description

Required. Text.

What the parameter means. The model reads it to choose a value.

description = "The order id, for example A-1001"

parameters.path › name

Required. Text.

The parameter’s name, as the endpoint expects it. A path parameter’s matches {name} in the URL.

name = "orderId"

parameters.path › type

Optional. One of the values below. Default: "String".

The type of value the model must give.

Value	Meaning
String	Text.
Number	A number that may have a fractional part.
Integer	A whole number.
Boolean	true or false.

type = "number"

parameters.path › required

Optional. true or false. Default: true.

Whether a call must give the parameter.

required = false

A complete example

From the 15-files-for-agents example project:

connectors/open-api/vfs-write.mtr

method = "PUT"
url = "https://api.maitento.com/vfs/by-id/{id}/files/write/text"
description = "Writes a text file to a virtual file system, replacing it if it exists"
auth = "Maitento"
schema.request = @json("vfs-write-request")
parameters.path = [
  {
    name = "id"
    description = "The virtual file system id"
  }
]
parameters.query = [
  {
    name = "path"
    description = "The file to write, for example /shopping.md"
  }
]