Connections and tools

A connection is a configured instance of a collection in one environment: a mailbox, a model provider, a Remote MCP Server. It has an identifier (its slug), which is how a workflow refers to it, and it may reference a credential, the secret it authenticates with. One environment can hold several connections of the same collection, for example two Outlook accounts.

Every connection has a direction, derived from its type: Outgoing connections are how the platform reaches a service on the agent’s behalf; Incoming connections are endpoints callers reach the platform through. This page covers outgoing connections. Incoming ones are on Chat, AG-UI and MCP endpoints.

The Connections page

Connections live in the Connections section of the environment’s Environment page. The header carries Add connection and a toggle between All, Incoming and Outgoing; every row carries its Direction tag. An outgoing row shows the collection’s icon, the connection’s name and identifier, and its health. Owned connections offer Test, Edit and Delete.

A connection is authored content. It is stored as .archmax/connections/<slug>.yml in the environment’s draft, and production sessions see it once the environment is published. Testing sessions, the editor’s chat and evaluations read the draft, so they see it at once. A connection file never holds a secret:

.archmax/connections/outlook-tobias.yml

version: 1
connection:
  type: ap
  piece: microsoft-outlook
  label: Outlook (Tobias)
  credential: outlook-tobias

The catalog

Add connection opens the catalog of what an environment can connect, whether or not a connection exists yet:

Catalog entry	Type	What it connects
An Activepieces piece (Outlook, Gmail, GitHub, …) the deployment offers	ap	The piece’s actions as tools, its triggers as triggers
A platform collection, such as REST API	platform	First-party tools; some are served by a service the operator deploys
Remote MCP Server	mcp	The tools an MCP server advertises over Streamable HTTP
Generic Model Provider, AWS Bedrock, Azure OpenAI	llm	The models an agent runs on (see Model providers)
AG-UI endpoint, MCP endpoint, Webhook	incoming	An endpoint callers reach (see endpoints)

Which Activepieces pieces are in the catalog is the operator’s choice: the config’s activepieces section names the ones the deployment offers, and a piece it does not name is not offered, nor is any piece when the section is absent. A connection of a piece the deployment stops offering resolves no tools until the piece is offered again.

One collection, Daytona, gives each session a sandbox to run commands in, with credentials for the commands’ own API calls that only Daytona’s egress proxy holds. It has its own guide: Sandboxes (Daytona).

A collection that needs no credential is not in the catalog: its tools are available in every environment without a connection. The files collection is one, and so is a service that declares no credential form, such as the Browser service where the operator deploys it (browser__fetch_url, browser__web_search).

An ap, platform or mcp connection exposes every tool of its collection unless it lists the ones it exposes (actions for ap and platform, tools for mcp). A connection carries nothing else about its tools: their inputs are the agent’s to choose, governed by the workflow.

Credentials

Registering a connection is one flow: pick the collection, enter a name and an identifier (fixed once created), fill the credential form, and Connect. The form is derived from the collection itself, from the piece’s authentication or a platform collection’s declared form, and secret fields are masked.

• Secret fields are kept in the deployment’s secret store: sealed with AES-256-GCM under its MASTER_KEY on the credential’s record, or in AWS Secrets Manager (see where credentials are kept). They are opened only in server memory when they are used, never shown again, never written to the environment’s files, and never placed in text a model reads. Deleting a connection’s credential removes its secret.
• When editing, leave a secret field blank to keep its stored value.
• Some fields are a list of rows, such as a Daytona connection’s egress secrets: a plus beside the label adds a row, and a bin removes it. A list’s secret column is masked and sealed with the credential. When editing, its other columns are shown, and a secret cell left blank keeps the one stored for that row.
• Credentials belong to the agent’s organization. Configuring connections and credentials — reading them, creating, editing, signing in to and deleting them — needs connections:read and connections:write, which only the agent’s Administrators hold. Using them does not: every turn resolves them, whoever started it, and a session that calls a connection’s tool needs only workflows:use (see Roles and groups).
• A credential is not part of the published version, so replacing one needs no publish.

Signing in through an OAuth app

Collections that authenticate with OAuth2 (Microsoft 365, Google Workspace, GitHub and others) are connected by signing in. When an OAuth app the operator registered serves the collection, Connect sends you to the provider’s sign-in; there is no client ID or secret to enter. A collection with settings to fill, such as Microsoft’s cloud, names the app above them; one with none, such as Google Drive or GitHub, is the connection’s name and Connect alone. The sign-in has to be finished in the browser that started it, within ten minutes: a consent link opened anywhere else connects nothing. Tokens are refreshed automatically. Reconnect repeats the sign-in for the same identifier.

When no OAuth app serves a collection, the dialog says this platform has no sign-in for it yet and keeps Connect disabled. A collection that offers app-only access (the .default access modes of Microsoft Outlook, Microsoft SharePoint and Microsoft Dynamics 365 Business Central) can still be connected with your own app’s client ID and secret, which the dialog asks for as soon as you pick such a mode, whether or not an OAuth app serves the collection. The app is one you register in your own Microsoft Entra directory with Application permissions and admin consent; replace the common the dialog prefills with that directory’s ID, since common only works for signing a person in. An app-only connection acts as the app, not as the person who connected it: it reaches whatever the app’s permissions cover (every site of your organization’s SharePoint, for SharePoint). Business Central also has to know the app: add its client ID on Business Central’s Microsoft Entra Applications page, enable it and assign it permission sets, which decide what the connection reaches in every company of its Environment.

A delegated connection acts as the person who signed in: the dialog shows who connected it, and turns using it act as their account. Some OAuth apps also describe their reach, what a connection can get at beyond that person’s own access, such as the repositories a GitHub App is installed on. The dialog shows the operator’s note and, where the provider has a page for it, a link or button to change it.

Note

Registering OAuth apps is the operator’s work: see Operating a deployment and the oauthApps list in the config.

Lite Google collections

Gmail, Google Drive, Google Sheets and Google Docs ask Google for restricted scopes. Google requires a yearly security assessment of the operator’s Google app before such a sign-in goes into production. Until the assessment is done, a deployment can offer their lite collections instead: gmail-lite, google-drive-lite, google-sheets-lite and google-docs-lite. The catalog shows them as Gmail, Google Drive, Google Sheets and Google Docs. They serve the full collections’ own actions and triggers, under the same names and inputs, but sign in for less. Of the actions, they serve those the piece’s authors made for agents, whose inputs a model can fill, and leave out those made for a form. What each reaches:

Collection	Reaches	Not served
gmail-lite	Sending email	Reading, searching, drafting, labelling or trashing messages, managing labels, and every trigger. Send Email’s In Reply To and Save as Draft fail with Google’s scope error
google-drive-lite	The files and folders created through archmax, by this or another lite collection: create, upload, download, share, move, comment and so on	Any other file of the Drive, which its searches, lists and triggers do not see; Empty Trash, the shared-drive actions, and Export Folder as Zip
google-sheets-lite	Reading and writing any spreadsheet you can open, by its id	Finding spreadsheets, a trigger’s spreadsheet picker, the New Spreadsheet trigger and the two row triggers see only the spreadsheets created through archmax
google-docs-lite	Reading and editing any document you can open, by its id	Searching, copying and exporting documents, the document picker and the New Document trigger see only the documents created through archmax

A spreadsheet or document created outside archmax is named by its id, the part of its address between /d/ and the next /. An agent passes the id as the tool’s input. In the editor, type the id into the picker’s search and choose Use this value: the picker lists only the files created through archmax, but takes any id typed into it. A spreadsheet an agent creates, and shares with people through google-drive-lite, is one the row triggers watch, and people’s edits to it fire them.

When the operator later offers the full collections, they appear in the catalog beside the lite ones, under the same names. Each one’s description says what it reaches. A lite connection keeps its narrower sign-in. To give an agent the full collection, add a connection of it and name that connection in the workflow in place of the lite one. Its actions keep their names and inputs.

Authenticating a Remote MCP Server

A Remote MCP Server’s dialog asks how the server authenticates. Pick the method the server’s documentation names:

Method	What the platform sends	Typical servers
None	Nothing	Public servers
OAuth sign-in	A token from signing in with the server’s authorization server	Linear, Notion, Atlassian, Sentry, Asana, Stripe, Cloudflare
OAuth app-only access	An app-only token minted with a client you registered	Servers offering machine-to-machine access
Bearer token	Authorization: Bearer <token>	A personal access token, such as GitHub’s
API key	The key in the header or query parameter you name, such as X-API-Key or apiKey	Servers that hand out keys

OAuth sign-in follows the MCP authorization specification. Connect asks the server where it signs people in (its protected resource metadata, then its authorization server’s metadata) and sends you there. There is no client ID or secret to enter: for each sign-in the platform registers itself with the authorization server, a client registration — through dynamic client registration where the authorization server offers it, otherwise as its client ID metadata document. The authorization server has to support PKCE. The sign-in asks for the scopes the server asks for unless you name your own, and it has to be finished in the browser that started it, as every sign-in here does. Its requests use https.

A server that supports neither way of registering cannot be signed in to by this platform: the dialog says so, and the server is connected with a token or an API key instead (GitHub’s, for one, takes a personal access token as a bearer token).

OAuth app-only access mints a token with a client ID and secret you registered with the server’s authorization server. The token acts as that client, not as you. On a reconnect a blank secret keeps the stored one, as long as the client and the server’s token endpoint are the ones it was given for.

The token of either OAuth method is bound to the server it was issued for. It is never sent to another address, so changing the connection’s URL to one outside that server signs you in again; nobody can redirect it by editing the credential, whose OAuth details are written by the sign-in alone. Tokens are renewed automatically before they expire, and once more when the server refuses one; Reconnect repeats the sign-in or the mint for the same identifier.

An API key named for the Authorization header sends exactly the value you enter, which is how a server expecting another scheme, such as Token <key> or HTTP Basic’s Basic <base64 of user:password>, is connected.

Request headers are for the parameters a server reads from its headers, such as GitHub’s X-MCP-Toolsets. They are stored in the connection file, so they hold no secret: Authorization, Proxy-Authorization and Cookie are refused there, as are the headers the connection sets itself. Each header is named once and holds plain ASCII text. Non-secret query parameters can stay in the server’s URL; a key that belongs in the query string is an API key placed in the query.

A new connection’s credential is named after the connection, or after it with a number when a credential of that name is left from a removed connection. To change how a server authenticates, remove its connection and add it again.

.archmax/connections/github.yml

version: 1
connection:
  type: mcp
  url: https://api.githubcopilot.com/mcp/
  headers:
    X-MCP-Toolsets: repos,issues
  credential: github

Model providers

An agent’s models come from a model provider, an llm connection selected on the Agent page with a model ID.

• Generic Model Provider: any OpenAI-compatible API, by base URL and bearer token. Its API is Chat Completions unless a model needs Responses.
• AWS Bedrock: the Bedrock Converse API in one region (such as eu-central-1), signed with an AWS access key ID and secret access key.
• Azure OpenAI: the Responses API of one Azure OpenAI resource, by resource name and API key. Pasting the resource’s endpoint fills in the name. The model ID is the name of a model deployment in that resource.

Every model call asks for up to 16,384 output tokens, whichever provider serves it, instead of the provider’s default (4,096 for an Anthropic model behind Bedrock or a LiteLLM proxy). A model or proxy that allows less refuses the call.

Each provider connection declares the rates its models are priced at, in USD per 1,000,000 tokens, keyed by model ID, with a default row for every other model. A key also prices every model ID that contains it, the longest matching key winning, so one row covers a model family. An empty cache rate is charged at the input rate. Without rates, spend on the connection cannot be measured and a spend cap is not enforced for it.

Health and testing

Registering an outgoing connection, changing its credential or reconnecting it tests it and reports the result, with the service’s own error message when it fails; renaming it does not. Test connection re-runs the test on a saved row. The health column reads Healthy, Unhealthy, Untested (never tested) or Configured (the collection offers no automatic check). What a test does depends on the type:

• an Activepieces connection runs the piece’s own credential check;
• a Remote MCP Server is checked with the MCP initialize handshake, with its headers and credential; one that answers that it requires authentication is reported as such;
• a Generic Model Provider or Azure OpenAI connection is asked for its models, then sent an empty request through the API it calls, and an AWS Bedrock one is sent a request naming a model that does not exist; the provider refuses either before any model runs, so nothing is billed;
• a service’s connection is checked by the service itself.

The add and edit dialogs of a Remote MCP Server and of a model provider can test the values you entered before you save; that test stores nothing.

Every URL you give the platform to call, such as a base URL or a Remote MCP Server’s URL, must use https (plain http only outside production, where a form allows it), carry no embedded credentials, and resolve only to public addresses. The check runs when you save and again on every call. The same rule holds for every request a collection makes on its own, its redirects included, and for a credential field that names a host, such as a database’s host or an S3-compatible endpoint: a private, loopback or link-local address is refused.

Where a collection’s code runs

A collection’s code never runs in the platform’s API or dispatcher processes. It runs in a worker, a process of its own that holds none of the platform’s secrets and opens no connection to its data stores. A session’s turn and the tools it calls share one worker. Every call made through a connection outside a turn gets one of its own: a connection test, a property’s options in the editor, a remote mount’s listings and reads, and each lifecycle of a piece trigger (see piece triggers). The catalog is read from the collections in a worker too.

A worker receives the credentials of the connections its turn or call uses, and of each only what the call presents. An OAuth2 connection presents its current access token. Its refresh token and its OAuth app’s client secret stay with the platform, which refreshes the access token when it falls due. A service’s credential reaches no worker, because the platform calls the service itself. A call whose worker fails, by running out of memory or time, fails with that reason, and a connection test reports it as the connection’s error.

Inheritance

An environment with a parent environment inherits the parent’s connections and credentials, nearest first. An inherited row is muted and tagged Inherited with its source environment, and offers only Test and Replace: Replace opens the edit form pre-filled and saves an owned copy under the same identifier, which then shadows the parent’s.

Granting a connection’s tools in a workflow

Registering a connection grants no tool. A workflow grants tools per state, by tool ID <collection>__<action>, in the editor’s tool list or in tools.allow. When the collection has more than one connection, the entry names the one to use; the tool’s Connection selector in the editor writes its connection key:

states:
  reply:
    tools:
      allow:
        - tool: microsoft-outlook__reply-email
          connection: outlook-tobias
          args:
            to: ["*@acme.example"]

A tool resolves through the connection its entry names, otherwise through the collection’s only connection. A tool whose collection has several connections and none named, or no connection at all, is unbound: the editor warns, and the agent cannot call it. A connection whose identifier equals the collection’s is not chosen for that reason. Name a tool’s connection the same way in every state that grants it.

A workflow that runs another one as a child session shares its tools with it: one tool, through one connection, serves both. The connection a sub-workflow names for a tool its caller does not grant holds in its child session. A tool the calling workflow grants runs through the connection the calling workflow names, or none. Sub-workflows that name different connections for a tool, or where one names none, leave it unbound. Either way the turn’s log says so: name the same connection everywhere a tool is granted.

args holds argument guards: glob patterns keyed by argument name, and a call is refused unless every guarded argument matches. A pattern can reference a session variable, such as ["${{from_email}}"]. See tool governance and tools.allow in the harness documentation.