Integrations

Connect your AI agents to external systems. Add an MCP server, import an OpenAPI spec, or configure HTTP endpoints by hand, then store credentials securely in the secrets manager and test everything from the dashboard.

Integrations extend your agent's capabilities beyond answering questions from the Knowledge Base. Through a connection, your agent can call external APIs during a conversation: look up live data, check stock, fetch order status, or trigger workflows in other systems.

You manage integrations under Integrations in the sidebar. The page has two tabs:

• Tools: the connections your agents can call, each one contributing one or more tools.
• Secrets: encrypted API keys and credentials, referenced from connections as $secret:key.

Connections and secrets are defined once per organization and shared across all agents. Each agent then chooses which connections it uses (see Attaching tools to agents).

Who can do what

Members do not see the Integrations entry in the sidebar and are redirected to Chat if they open the URL directly. Builders can view everything and wire existing tools into agents, but creating or changing connections and secrets requires the Admin or Owner role.

Built-in tools

Besides connections, agents have a set of built-in tools. Most of them are configured in the agent editor (Configure tab), not on the Integrations page:

Connections

A connection is one external system your organization has wired up. Each connection contributes one or more tools that an agent can call when it decides the action fits the conversation.

The URL and the credentials are configured once, on the connection. Everything under it inherits them, and each agent then switches on the connections it needs, with all of their imported tools.

There are two kinds, chosen on the first step of the add flow:

A third card, Managed, is visible only to botts.ai platform staff. See Managed tools.

Adding a connection

Click New Tool on the Tools tab. The add flow is a three-step wizard, shown as a Source → Connection → Import indicator you can click to move back and forth between steps you've already visited.

When you edit an existing connection you start on step 2. The source of a connection cannot be changed after it is created.

The catalogue

Step 1 shows a curated catalogue of about two dozen vendors under Popular integrations, as one list with the ones you can connect today first. Search filters it by name, description or category (CRM, commerce, support, productivity, marketing, payments, Swiss business software). Most entries are MCP servers; a few, including Bexio, weclapp and lexoffice, are OpenAPI imports, and each entry carries an MCP or API chip saying which.

Each entry carries a trust badge and an authentication hint. The badges are Official (the endpoint is the vendor's own, taken from their documentation or their registry entry), Verified, and Community. Every entry in the catalogue today is Official. The authentication hint is No login, API key, or OAuth (soon).

Every catalogue URL was probed from botts.ai's own backend, either completing a full MCP handshake or answering with an authentication challenge that proves the URL and transport are real. Entries whose only supported login is OAuth are shown but disabled, because the MCP client does not yet run an interactive OAuth flow. Entries needing more custom headers than the form stores are disabled for the same practical reason.

MCP servers

The Model Context Protocol (MCP) is an open standard for exposing tools to AI assistants. Rather than describing every endpoint yourself, you point botts.ai at a remote MCP server and it asks the server what it can do.

Connecting a server

1. Choose MCP server on step 1, or pick an MCP vendor from the catalogue.
2. Enter the Server URL (for example https://api.example.com/mcp/) and a Server name. The name and description are taken from the server when it connects, and you can adjust them.
3. Set Authentication if the server needs it: None, Bearer Token, Basic Auth or Custom Header (see Authentication). Login Token works for HTTP API connections only, and MCP connections have no Additional Headers field.
4. Run the connection check. botts.ai completes an MCP handshake and lists the server's tools.

Servers disagree about whether they answer at /mcp or /mcp/. If the check or the tool list fails at the address you typed, botts.ai retries once with the trailing slash flipped and, if that works better, puts the working variant into the field for you.

Importing tools

Discovering a server's tools does not activate them. On the Import step, click Load tools: botts.ai asks the server for its tools and lists them with their descriptions. On the first load every tool is ticked; untick the ones you don't want, then click Save (it stays disabled until at least one tool is ticked). To change the selection later, expand the tool count on the connection card, click Manage tools, then Reload and Save. Each imported tool becomes a normal agent tool on every agent that has this connection switched on.

The tools are registered under a namespaced name, servername__toolname, so two servers offering a search tool never collide.

When a server changes

botts.ai stores the tool definitions you imported, and your agents use exactly those. If the server later adds, changes or removes tools, nothing changes for your agents until an admin opens Manage tools, clicks Reload and saves.

On a reload, tools you had imported stay ticked as long as the server still offers them, tools the server dropped disappear, and newly offered tools arrive unticked, so nothing new is ever approved automatically. Saving adopts the server's current descriptions and input schemas for the ticked tools, so read them before you save. This is deliberate: a tool description is an instruction to your model, so a server that silently redefines a tool could otherwise change what your agent does.

Changing a connection's server URL, or switching its credential between an organization and a personal secret, clears its imported tools. The dashboard then shows "Server changed: reload and confirm its tools."

HTTP API connections

An HTTP API connection is a base URL plus a set of endpoints. Credentials are configured once on the connection and apply to every endpoint under it.

Endpoints

Each endpoint under the connection becomes one tool the agent can call:

Every endpoint whose method is not GET is marked with a writes badge, and the endpoint list shows how many of them write (for example "5 endpoints · 2 writing"). An endpoint with no description is flagged, because the AI has no basis for choosing it.

Importing from OpenAPI

If the API publishes an OpenAPI specification, you do not have to type the endpoints out.

1. Create or edit an HTTP API connection and find Import from OpenAPI beneath the endpoint list.
2. Give it the URL of the spec (for example https://api.example.com/openapi.json). JSON and YAML are both read, and botts.ai looks for a spec automatically under your base URL, telling you when it finds one. The spec has to be fetchable at a URL: there is no box to paste one into, so a spec you only hold locally needs hosting somewhere reachable first.
3. Review the proposed endpoints. Search narrows the list, and All / None select in bulk.
4. Import your selection.

Endpoints that write are not pre-selected. You opt into those deliberately. When a spec has more than 25 read endpoints, none are pre-selected: search for the ones you need and tick them. The search box appears once a spec has more than 12 endpoints, and All / None act on the current search results.

Parameters

Each parameter has a name, a type (string, number, integer, or boolean), a description for the AI, and a required flag. The parameters become the tool's function signature: the model reads the names, types, and descriptions to decide which values to pull from the conversation. Precise descriptions directly improve how reliably the agent fills in arguments.

Two options change what the model sees:

• Restrict to allowed values turns a parameter into a fixed list of options, so the model cannot invent a status or category your API does not accept.
• Fixed turns a parameter into a constant the AI never sees and cannot change. It is sent on every call, and the value may be a $secret:key reference. Use it for tenant ids, account numbers, and other values that belong to the connection rather than the conversation.

Parameters derived from a {param} placeholder in the path are managed by the path itself: remove the placeholder to remove the parameter.

Authentication

Token, password, and header-value fields all accept $secret:key references, and each field has a $secret picker chip that inserts one for you. You can also create a secret inline, without leaving the form. Always store credentials as secrets instead of pasting them in plain text.

Login Token

Some APIs do not issue long-lived keys: you post credentials to a login endpoint and use the token that comes back. Login Token auth does that for you.

A cached token that is refused before its lifetime runs out (revoked, rotated, or the upstream restarted) triggers one automatic re-login and a single replay of the request.

Auth scope: shared or per user

Every connection runs under either a shared or a personal credential. You don't choose this separately: it follows the secret you put into the Auth fields.

Once a secret is referenced, the form shows which of the two applies above the Auth fields, and the connection card shows it next to the URL. When you create a secret inline from the $secret chip, its Org / Personal switch is what makes the connection organization-wide or per user.

Per user is how you let a team share one connection while each person acts as themselves in the external system. It has two consequences worth knowing: it does not work on public agents (a website visitor has no botts.ai account), and it does nothing for a member who has no personal secret stored under the connection's key. Only an Admin or Owner can create secrets, so an admin stores each colleague's credential for them with the Only {name} scope (see Secrets). To test or load tools on a per-user connection, the admin needs a personal secret of their own under the same key; otherwise the check reports Your own credentials needed.

A per-user connection resolves only each member's own secrets, so mixing a personal secret with organization secrets in the Auth fields would work for nobody. The form warns you when the fields are mixed and refuses to save.

How requests are sent

• GET and DELETE: Tool arguments are sent as URL query parameters, merged with any query string already in the endpoint.
• POST, PUT, and PATCH: Tool arguments are sent as a JSON request body.
• Path variables: If the path contains {param} and the model provides a matching argument, it is percent-encoded, substituted into the URL, and removed from the remaining arguments. Example: orders/{order_id} with order_id: 1234 becomes orders/1234.
• Secrets: $secret:key references in the URL, headers, and auth fields are resolved at call time. If a referenced secret does not exist, the placeholder is sent as literal text.
• Timeout: In chat, calls time out after 30 seconds. On voice (phone and widget voice), a tool call is stopped after 15 seconds and the agent is told it timed out.

Responses and error handling

• Success (2xx): The response body is passed to the model as-is (JSON is serialized, plain text stays plain text). Very large responses are capped at about 50,000 characters, keeping the beginning and the end, so one oversized result cannot crowd out the conversation. On voice the limit is much tighter: all tool results of one turn share about 24 KB, so give endpoints that a phone or voice agent uses a response pipeline.
• HTTP errors (4xx/5xx): The response body is hidden from the model for security. The agent is told only The external API returned HTTP <status>., plus a short hint derived from the status code alone telling it what to do next and not to invent the data.
• Connection failures: The agent sees The external API call failed. and a hint telling it to report the integration as unreachable rather than guessing.

This means: anything you want the agent to read and relay to the customer must come back with a 2xx status code. For example, if a product is out of stock, return 200 with {"in_stock": false, "restock_date": "2026-09-01"} rather than a 404.

Because connections can have side effects (booking an appointment, creating a ticket), the platform never automatically retries them or re-runs a conversation turn after one has executed.

Response pipeline

Some APIs answer correctly but unhelpfully: a hundred records where the agent needs five, or fifty fields where two matter. A response pipeline trims the response before the model ever sees it, which cuts both cost and confusion.

Open Response pipeline (advanced) on an endpoint and give it a JSON list of steps, applied in order:

An argument that a search or filter step reads is used by the pipeline only and is not sent to your API, so you can add it as an extra parameter on the endpoint.

[
  { "step": "project", "fields": ["id", "name", "status"] },
  { "step": "search",  "arg": "query", "over": ["name"], "min_score": 60 },
  { "step": "sort",    "by": "name", "order": "asc" },
  { "step": "top",     "n": 5 },
  { "step": "render",  "format": "tsv", "empty_text": "No matching records." }
]

The pipeline is validated when you save, so a malformed step is rejected at configuration time rather than mid-conversation.

Security: blocked endpoints

To prevent abuse, connection endpoints are restricted:

• Only http:// and https:// URLs are allowed.
• Before each call, the hostname is resolved and checked. Endpoints that point to private networks, localhost, link-local or cloud-metadata addresses, or other internal or reserved ranges are blocked, as are hostnames that fail to resolve.

A blocked call returns Endpoint blocked by security policy. In plain terms: your connections can reach the public internet, but not internal or private hosts. The same check applies to MCP server URLs. If you need to integrate dedicated or internal infrastructure, see Managed tools.

Testing a connection

Testing happens in two levels, and the test dialog asks them as two separate questions.

Level 1: does the connection work? For an MCP server this is a handshake that proves reachability and valid access, with no parameters needed. For an HTTP API it is one call to the base URL. The verdict is reported plainly: Connection works, Server unreachable, Access denied, Server error, Address blocked, Invalid URL, Secret missing, or Your own credentials needed (a per-user connection you have no personal secret for).

A base URL that answers without checking credentials gives one more verdict, Server reachable: the address is real but says nothing about your key. That is not a failure, and it is why level 2 exists.

Level 2: is the tool configured correctly? Pick an endpoint or a discovered tool and run it. Parameters are pre-filled with example values from the schema, so most tests are one click. You can edit them in a form or as raw JSON, and switch the result between a readable overview and the raw payload. If the endpoint has a response pipeline, the result is what the agent would receive after the pipeline, and a broken pipeline shows as Tool reports an error. A dashboard test waits up to 10 seconds for your API, less than the 30 seconds a live chat call gets.

An endpoint that writes asks you to confirm before it runs, because the test is a real call against your real system.

Testing requires the Admin or Owner role. Once the direct test passes, use the agent's test chat for an end-to-end check: verify the agent picks the tool at the right moment and extracts the parameters correctly. To keep that check, save the conversation as a test (see Testing). In test runs, connections start switched off and are marked Can perform real actions: switch one on and each test really calls it, without retries. Per-user connections are not available in tests.

Attaching tools to agents

Connections live at the organization level; each agent picks the connections it uses:

1. Open the agent in the agent editor (Configure tab).
2. Expand the Tools section. It lists every connection in your organization (each MCP server and each HTTP API) with one toggle switch each, and the section header shows how many are attached.
3. Toggle on the connections this agent should use.

Switching a connection on gives the agent all of the tools imported on it. To keep a tool away from your agents, leave it out of the connection's import.

If no tools exist yet, the section links to the Integrations page. Builders can attach and detach tools here even though they cannot create new ones.

A per user connection shows a Per user badge and names the keys under which each member needs a personal secret for it to work for them.

A connection can also be disabled globally for the whole organization. It then shows a Disabled globally badge in the agent editor and is skipped by every agent until re-enabled, regardless of the per-agent toggles. There is currently no dashboard switch for this global flag; it is only available through the API.

Managed tools

A connection has a Type that also includes Managed. Managed connections are provisioned by botts.ai platform staff for dedicated or internal infrastructure, for example an ERP or factory bridge running in your environment. Compared to regular connections, managed ones:

• Bypass the private-network blocking, so they can reach internal hosts.
• Automatically retry on connection errors (up to 3 attempts, 1 second apart). Regular connections never retry.
• Show an amber Managed badge in the list.

You cannot create managed connections yourself; the Type selector is restricted to platform staff. If you need a dedicated integration to internal systems, contact botts.ai.

Secrets

The Secrets tab is the secure store for API keys and other credentials your connections need. Each secret has:

• Name: A display label, e.g. "Acme API Key".
• Key: The identifier you reference as $secret:key, e.g. acme_api_key.
• Value: The credential itself.

Security properties

• Secret values are encrypted at rest on Swiss infrastructure, and botts.ai never shows them back to you. They are of course sent to the system they authenticate against, which is wherever that vendor runs, so a credential's own residency follows the connection you use it on.
• Values are write-only: after creation, neither the dashboard nor the API ever returns a secret's value. The list shows only the name, key, and scope. In test results, resolved secret values are redacted in the displayed URL, but the response body is shown unmodified, so an endpoint that echoes the request returns them in full.
• There is no edit function. To rotate a secret, delete it and recreate it with the same key. Connections referencing $secret:key keep working without changes.
• $secret:key references resolve in the URL, header values, and authentication fields at call time.

Scopes

Use organization secrets for any connection an agent uses in live conversations on a public channel. Personal secrets resolve only for their own member's requests, so a website visitor's conversation would find nothing.

The third scope exists for a practical problem: a per user connection only works for members who have a personal secret under its key. An admin can use Add for another user on an existing personal secret (a key with no organization-wide value) to store the same key for a colleague, so the connection works for the whole team without anyone sharing a password. The key stays locked to the original when you do this; only the user and the value are set.

A duplicate key within the same scope is rejected; pick a unique key per secret.

Best practices

1. Write clear descriptions. The agent decides when to use a tool based on its description. Vague descriptions lead to the tool being used at the wrong time. The same goes for parameter descriptions: they steer what the model extracts.
2. Import the endpoints you need, not all of them. Every attached tool is text in the model's prompt. Twenty endpoints where three would do makes the agent slower, more expensive, and less decisive.
3. Keep APIs fast. The agent waits for the response before continuing the conversation (up to 30 seconds in chat, 15 seconds on voice). Slow APIs create awkward pauses.
4. Return useful information with a 2xx status. The agent never sees the body of a 4xx or 5xx response, only the status code. If "not found" or "out of stock" is something the agent should explain to the customer, return it as a 200 with a descriptive JSON body.
5. Trim big responses with a pipeline rather than letting the model wade through them.
6. Store credentials as secrets. Never paste API keys directly into URLs or headers; use $secret:key references so they stay encrypted and redacted.
7. Test both levels first. Verify the connection, then the endpoint, then use the agent's test chat to confirm the agent triggers the tool at the right moment, and save that conversation as a test.
8. Start simple. Begin with one connection and a couple of endpoints, and expand as you learn how your agent uses them.

Last updated on October 7, 2026