Let people add connections
A connection is a tool server that a person adds to an org through their agent, rather than one you set up in Auto's settings file. The org owns it, and every playbook of the org may use it, or only the playbooks it names. The person approves it, and gives its credential where it takes one, on a page of Studio. The agent never sees the credential.
This page is for whoever runs Auto. It says how a connection is added, what it holds, how a function uses it, and the rules you set for it in auto-runtime.yaml. A tool server you set up yourself is still added as Add a tool server shows.
How a person adds a connection
- The person asks their agent to connect a tool server, such as their CRM. The agent calls
add_connectionwith the server's address, its options and how it is credentialled, never the credential itself. - Auto keeps the connection,
pending, and answers with a link to Studio's page,https://studio.on.auto/connect, which lasts ten minutes. An agent whose client opens links asks the person to open it; any other agent gives the person the link from its answer. - On the page, signed in, the person approves the connection. Where it takes a secret or client credentials, the person types the credential there, and giving it approves the connection. The connection is then
connected.
On a runtime that signs people in, only the person who added a connection may approve it, signed in as themselves. In local mode, the link alone binds: whoever holds it within its ten minutes approves the connection. A link is gone after its ten minutes, and nothing gives a pending connection another, so the way on is to remove the connection and add it again.
list_connections shows the connections of the org and whether each is pending, connected, broken or removed; Studio reads one with get_connection. remove_connection removes one for good: no playbook may use it any more, and Auto forgets its credential. An org holds at most 50 connections that are not removed; add_connection refuses another with 409, conflict of the kind connections_full, until one is removed. The MCP reference describes the three tools, and the HTTP reference the routes, those of Studio's page among them.
How a function uses a connection
A connected connection is a tool server of its org, for every playbook of the org or the playbooks its entry names. A function names its tools as it names those of any tool server, by the connection's name and the tool, as in crm/search or crm/*, and calls them in the same way, with the same bounds and the same scrubbing of its credential from everything Auto records. search lists it beside the tool servers of the settings file, with connection, its id, and introspect, dry_run and execute reach it. Each call it records, a run's, one made by hand with execute and one an interaction function makes in a conversation, names the connection's id beside the server's name as connection_id, so the history stays plain once another connection takes the name.
A connection that is not ready is refused, and search lists it unavailable with the same words:
| The connection | A function that names it is refused with | Its words say |
|---|---|---|
| Nobody has approved it yet | connection_pending | The person who added it opens its link, or removes it and adds it again for a new link |
| Its credential cannot be read | connection_broken | Why, and that the person who added it removes it and adds it again |
A rule of auto-runtime.yaml no longer takes it | connection_not_allowed | The rule, in the sentence add_connection would give |
people_may_add is now false | connection_not_allowed | That this runtime uses no connection, since you set up its tool servers yourself |
| Its entry is no longer one Auto takes, as when a model provider you set up since has its name | connection_not_allowed | What add_connection would refuse in it |
Its reference names a variable that is not set | connection_not_allowed | The variable, and that you set it and start Auto again |
| Its name is that of a tool server of the settings file, for any org, which a later edit added | connection_not_allowed | That the settings file sets up a tool server of that name, and that it is removed and added again under another name |
| Its document names a server, or a call meets a redirect or an authorization server, on a host the rules do not allow | connection_not_allowed | The rule |
Each comes as unavailable of the kind tool_not_offered, before the function calls anything. A name that is neither a tool server of the settings file nor a connection of the org stays tool_server_not_configured.
Auto checks the rules, and checks the entry as add_connection checks it, when a connection is first used after Auto starts, once for each connection, and reads its credential then. A rule you change reaches a running Auto when it starts again. A connection Auto cannot read the credential of is broken for good: Auto records why, and the person removes it and adds it again, since nothing mends a broken connection. Where Auto cannot record it broken, it logs why, refuses it all the same, and reads the credential again at its next use, recording the break again.
Auto places the credential in the entry as the settings file places a reference to an environment variable, and reads the entry as it reads one of the file, with the same checks and the same secrets to scrub; the entry itself is sent as it is written, a $ in it too. The document of an HTTP API is read when a function first uses the connection. A document that cannot be read just now, because its address does not answer in time, answers an error or answers a page that is no document, such as a proxy's error page, is read again at the next use; one refused for what it says stays refused until Auto starts again, and the person removes the connection and adds it again once the document is put right.
Which runtimes take connections
A person approves every connection, so a connection is added by a person, and a runtime takes connections only where a person reaches it as themselves:
| Runtime | Who adds a connection | The runtime the link names |
|---|---|---|
One that signs people in, with PUBLIC_URL set | A person, through an agent signed in as them. add_connection refuses a key with 403, since no person would approve what it adds | PUBLIC_URL |
| One in local mode | The local developer | The runtime's loopback address |
One of API_KEYS alone, which signs nobody in | Nobody: add_connection refuses every connection with 403, since no person could approve it. Set PUBLIC_URL to sign people in, or add the server to auto-runtime.yaml as Add a tool server shows |
What a connection holds
A connection has a name, which a function will give it as a tool server's name, a kind, an entry and a credential.
| Part | What it holds |
|---|---|
name | 1 to 32 lowercase letters, digits and hyphens, starting with a letter. It may not be the name of a tool server of the settings file, nor of another connection of the org that is not removed |
kind | mcp for a remote MCP server, openapi for an HTTP API described by an OpenAPI document |
entry | The server without its credential: url for mcp, or document and base_url for openapi, with headers, query_params, allowed, playbooks, record_content and request_id as an entry of the settings file has them |
credential | How the server is credentialled, below, never its value: one object, its kind and the fields that kind takes |
Auto checks an entry as it checks an entry of the settings file, and refuses one that holds a value that looks like a credential, or a reference to an environment variable such as ${CRM_API_KEY}. A connection's url and document are each an https URL, or an http URL on a loopback address; a document is never a file on Auto's disk.
The kinds of credential
| Kind | What the person gives | Where the value is kept |
|---|---|---|
none | Nothing; the server takes no credential | Nowhere |
reference | Nothing; variable names an environment variable of Auto, such as CRM_API_KEY, that you set and list in the rule variables, and name and in say where its value goes, as for a secret | In Auto's environment, where you put it |
secret | A key or token, on Studio's page. name and in say where it goes: in: header and the header's name, never one Auto sets itself such as Content-Type, Host or Mcp-Session-Id, or for an HTTP API in: query and a query parameter's name, or in: security and a scheme of its OpenAPI document | Sealed in Auto's secret store |
client_credentials | The client secret, or a private key with its algorithm, on Studio's page. issuer, client_id and scope name the authorization server and the client | Sealed in Auto's secret store |
Auto seals a secret under its secret key, SECRETS_KEY or the key file beside a SQLite ledger, as the configuration reference sets out. No record of the org, no answer and no history holds the value, and the link's token is kept only as its SHA-256. Of a secret or a client secret of twelve characters or more, Auto also keeps its last four characters beside the sealed value in the secret store, never in the org's record, and list_connections and get_connection answer them as credential_ends_with, so the person can tell which key a connection holds; a private key, or a shorter value, has none. Removing a connection forgets its secret, and the ending with it.
Every value of a credential is a secret Auto scrubs from what it records and answers, in each form it may take, as it scrubs the value of a reference of the settings file. A value in a header that is a scheme and a credential, such as Bearer <token>, is scrubbed whole and its credential alone.
A secret is only as recoverable as the key it was sealed under. When the key is lost, Auto can no longer read the credentials sealed under it, so their connections are broken. Auto marks such a connection broken when it first needs the credential, with a sentence that says why; the person removes it and adds it again.
Set the rules in auto-runtime.yaml
A connections section of auto-runtime.yaml says what people may add. Every rule has a default, so a file without the section lets people add any connection but one of the credential reference.
connections:
people_may_add: true
allowed_hosts: ['*.example.com', 'crm.example.com']
credential_kinds: [none, reference, secret, client_credentials]
variables: [CRM_API_KEY]| Rule | What it does | When left out |
|---|---|---|
people_may_add | false refuses every new connection, and Auto uses none of those already added: list_connections still lists them as they are, connected among them, and a function that names one is refused. You set up every tool server yourself | true |
allowed_hosts | The hosts a connection may reach. A pattern is a host, or *. and a host for every host under it, so *.example.com takes crm.example.com and not example.com. Auto checks the host of an mcp connection's url, of an openapi connection's document and base_url, and of the issuer of client credentials, where the client secret or the key's assertion goes, and then every request a call makes before it is sent | Every host, addresses inside your network such as localhost or 10.0.0.5 among them, so set it wherever a connection must not reach those |
credential_kinds | The kinds of credential a connection may take, of the four above | Every kind |
variables | The environment variables a reference may name. A reference sends the value of a variable of Auto to the server the person names, so you list each one a connection may send; Auto refuses to start on a list that names a variable it reads for itself, such as SECRETS_KEY, API_KEYS or a provider's key | None, so every reference is refused |
add_connection refuses a connection a rule does not take with 403, saying which rule, such as A connection may not reach the host api.billing.example.org on this runtime, which allows *.example.com and crm.example.com. A connection added before a rule changed is refused the same way when it is first used after Auto starts again, connection_not_allowed with the same sentence. A rule the file gives that Auto cannot read stops it at start, naming the line. CONNECTIONS, the same rules as JSON, wins over the file. The configuration reference lists the section.
allowed_hosts holds more than the addresses a connection names: the server an HTTP API's document names, where base_url is left out, is checked once Auto reads the document, and every request a call makes is checked before it is sent, those to an authorization server and those a redirect leads to among them. A call of an HTTP API follows no redirect, and the MCP client follows one only within the origin it asked.