Skip to main content

Tools and connectors

A connector links a project to an outside system. Each connector gives agents one or more tools. An agent can call a tool only if it was given that tool when it was saved.

Every tool call goes through the same path:

  1. The agent's run checks whether the call can change data. If it can, the run waits for a person to approve it. See Human approval.
  2. The tool execution service asks the policy engine whether this project may call this tool. See Policy.
  3. It checks the destination against the connector sandbox, reads the credentials from Vault and makes the call.
  4. The call is recorded in the audit log and counted in the connector's usage.

You need the developer or admin role on the project to add or remove connectors.

Connector types​

TypeTools it gives agentsReads or writes
SQL database: PostgreSQL, MySQL or MariaDB, SQL Server or Azure SQL, Oraclequery_database, describe_schemaRead only. Only a single SELECT is accepted.
REST APIOne tool per operation you define or import from OpenAPIGET operations read. Every other method writes.
MCP serverThe tools the server listsEach tool writes until a developer or admin marks it read-only. See MCP servers.
GraphQL APIquery_graphqlRead only, unless you turn on Allow mutations.
Salesforcesalesforce_query, salesforce_get_record, salesforce_create_recordsalesforce_create_record writes. The others read.
Microsoft 365o365_send_mail, o365_list_events, o365_list_fileso365_send_mail writes. The others read.
EchoechoFor testing only. It returns what it is sent.

Knowledge base search is a tool too. You do not create a connector for it: pick the knowledge base on the agent. See Knowledge bases.

SQL Server and Oracle connectors, and act as each user on any connector, need the enterprise_connectors licence feature to create or switch on. Connectors that already use them keep running if the licence changes.

Add a connector​

  1. Open Connectors and choose New connector.
  2. Pick a type. The next step asks only for what that type needs.
  3. Enter a name. The slug is filled in from it and cannot be changed later.
  4. Fill in the connection and credentials. Secrets go to Vault when you create the connector. They are never stored in the database or shown again.
  5. Review What agents will get, then choose Create connector.

Then give the tools to an agent: edit the agent and pick them under Tools.

note

Connectors keep their credentials in HashiCorp Vault. If your install has no Vault configured, creating a connector fails. See Requirements.

SQL databases​

Pick the database type, then enter the host, port, database (the SID for Oracle, or a service name), username and password.

DatabaseDefault portRead-only transaction
PostgreSQL5432Yes
MySQL, MariaDB3306Yes. MySQL 5.7.8 and later also get a statement time limit.
SQL Server, Azure SQL1433No. Use a login with only db_datareader.
Oracle1521Yes. No Instant Client needed.

Optional settings:

  • Schema, and a list of allowed tables. With a list, every table a query names must be on it.
  • Maximum rows per result, 100 by default and at most 1000.
  • Timeout, 15 seconds by default and at most 60.

query_database(query, params) runs one SELECT, with values bound by the driver from :name placeholders. describe_schema(table?) lists the tables, or one table's columns.

Before a query reaches the database, Orchestrate refuses more than one statement, anything but SELECT, data-changing keywords anywhere (SELECT ... INTO, FOR UPDATE, a data-modifying CTE), cross-database names, table functions, and the known file, network and sleep functions such as pg_read_file, xp_cmdshell, OPENROWSET, UTL_HTTP and LOAD_FILE. The login's own rights are still the real boundary, so use one that can only read what the agent needs.

REST API​

Enter the Base URL and how to authenticate:

  • None
  • API key, sent in a header you name
  • Bearer token
  • OAuth2 client credentials: a token URL, client ID and client secret

Then define the operations, or import them from an OpenAPI description. Each operation becomes one tool:

FieldExample
Tool nameget_invoice
MethodGET
Path/invoices/{invoice_id}. Put path parameters in braces.
Description"Fetch one invoice by its ID, including line items and status." The model reads this to decide when to call it.
ParametersName, type, description and whether it is required

For GET and DELETE, parameters that are not in the path are sent as a query string. For other methods they are sent as a JSON body. The model fills in the parameters, but it can never change the method, the base URL or the path template.

GraphQL API​

Enter the Endpoint and the authentication, using the same options as a REST API. By default, agents can only send queries: a mutation or subscription is refused before it is sent. Turn on Allow mutations to let agents change data. Every call then waits for approval.

Salesforce​

Check the Token URL. It defaults to https://login.salesforce.com/services/oauth2/token. Use https://test.salesforce.com/... for a sandbox org. Then choose the OAuth2 flow:

  • Client credentials: client ID and client secret
  • Username and password: client ID, client secret, username, password and, if your org requires one, the security token

Microsoft 365​

Register an app in Microsoft Entra ID and enter its Tenant ID, Client ID and Client secret. For o365_send_mail, also enter the Sender mailbox that mail is sent from.

Act as each user​

By default a connector calls the outside system with its own credentials, as the app. REST API, GraphQL, MCP, Salesforce and Microsoft 365 connectors can instead act as each user: each person connects their own account once, and the agent then calls the system with that person's token, so the system applies that person's own permissions.

To switch it on, turn on Act as each user on the connector and pick the sign-in provider: Microsoft, Google, Salesforce, or any other OAuth 2 provider with its authorize and token URLs. Register this redirect address with the provider:

https://<your console>/connections/callback

Salesforce and Microsoft 365 use the connector's own client ID and secret for the sign-in. The other types take an OAuth client ID and secret, which go to Vault.

How it works:

  • Connecting. People connect on the Connected accounts page, with the authorization code flow and PKCE. The sign-in link is single-use and expires after 10 minutes.
  • Storage. Tokens are kept in Vault, per person. Orchestrate records who connected, never the token itself. Tokens are refreshed when used. A refresh the provider refuses marks the connection Needs reconnecting.
  • Disconnecting. A person disconnects on Connected accounts. A developer or admin of the project can disconnect anyone from the connector's People connected list. Either way the provider's revoke address is called, when it has one, and the token is deleted.

Whose token a run uses comes from who called, never from the request body:

CallerToken used
A person in the console, or signed in to the hosted chatTheir own
The Agent API with a project key and a userThat application user's. They connect through a consent link the application requests with POST /connectors/{id}/oauth/consent-links and sends them.
A Teams user matched to a Orchestrate accountThat account's. See Channels.
Anonymous chat, or a personal API keyNone. The connector refuses the call.
Coming

Code agents calling a connector through the platform's MCP tool server don't act as the user yet.

Writes and approval​

Orchestrate decides whether a tool call can change data from the connector as it is configured at the time of the call:

  • Salesforce salesforce_create_record and Microsoft 365 o365_send_mail always write.
  • A REST operation writes unless its method is GET.
  • A GraphQL call writes when Allow mutations is on.
  • An MCP tool writes unless it was marked read-only.
  • SQL connectors, Echo and knowledge base search never write.
  • Anything Orchestrate does not recognise counts as a write.

By default, an agent run stops before every write and waits for a person. See Human approval.

The baseline policy also limits two write tools, salesforce_create_record and o365_send_mail, to the projects on an allow list. Out of the box that list has only the Default project. In any other project those two tools are refused until a platform admin allows them with a custom policy. See Policy.

Where connectors may connect​

Tool execution is the one service that connects to your databases and APIs, so it is fenced in two ways:

  • The connector sandbox, always on. It refuses the platform's own services by name, every pod, node and service address in the platform's namespaces, loopback, and link-local and cloud-metadata addresses, whether the connector names them directly or a hostname resolves to them. While the list of platform addresses is unknown or stale, it refuses every private address. Redirects are not followed.
  • A NetworkPolicy, which your operator can turn on. Then tool execution reaches only the platform services it needs, public HTTPS if allowed, and the destinations your operator lists. On an air-gapped install, every database, REST API and MCP server must be listed. See Configuration.

Usage​

Every call is counted per connector per day: calls, errors, calls made as a user, and SQL rows returned. The connector panel shows the counts.

Remove a connector​

Open the connector, choose Remove connector… and confirm. Orchestrate deletes its credentials from Vault and the connector from the project. The connector page lists the agents that use it, so check them first: their calls to its tools fail after it is removed.

Limits​

  • A tool call times out after 30 seconds. HTTP calls to REST, GraphQL, Salesforce and Microsoft 365 time out after 15 seconds. SQL queries use the connector's own timeout.
  • In an agent run, a tool that can change data is tried once, so a failed write is not sent again. A read-only tool is tried up to three times.
  • Results are sent back to the model as text. Large results use up the model's context.
  • Tool call arguments and tool results are scanned for personal data. See PII guardrails. Tool results are also checked for prompt injection. See Guardrail profiles.
Was this page helpful?