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 tools it actually 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. These 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 picks which of the resulting tools it actually uses.

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, grouped by category (CRM, commerce, support, productivity, marketing, payments, logistics, and Swiss business software). Search filters the list. Most entries are MCP servers; a few, including the Swiss accounting tools, are OpenAPI imports.

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 (see Authentication).
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 a connection check stalls, the form offers the same URL with its trailing slash flipped rather than making you guess.

Importing tools

Discovering a server's tools does not activate them. Open Manage tools on the connection card, load the tool list, tick the ones you want, and import your selection. Each imported tool becomes a normal agent tool that you then switch on per agent.

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 fingerprints the tool list each time it syncs and shows you a diff: tools marked new, changed (same name, different description or input schema), and any that the server no longer offers.

Newly discovered tools are never approved automatically. A changed server shows "Server changed — reload and confirm its tools" and your agents keep running the previously approved set until you re-approve. 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.

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:

Endpoints that change data are marked with a writes badge, and the connection card shows how many of its endpoints write. 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.

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 chooses who its credential belongs to:

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 not stored their own secret. See Secrets for how an admin can store one on a colleague's behalf.

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.

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 — Live calls time out after 30 seconds.

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, keeping the beginning and the end, so one oversized result cannot crowd out the conversation.
• 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:

[
  { "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, address blocked, or a referenced secret is missing.

A base URL that answers without checking credentials gives a fourth kind of 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.

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.

Attaching tools to agents

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

1. Open the agent in the agent editor (Configure tab).
2. Expand the Tools section. It lists every tool in your organization with a toggle switch per tool, and the section header shows how many are active.
3. Toggle on the tools this agent should use.

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 tool from a per user connection shows a Per user badge and tells you which secret keys each member needs to store for it to work for them.

A tool 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 stored their own credential. An admin can use Add for another user on an existing secret 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 the 30-second timeout). 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.
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 September 13, 2026