User guide
Connections
You want the agent to do something it did not ship with and no website offers. A connection is how you give it that ability.
A connection is a tool server: a program, running on your machine or somewhere on the network, that offers the agent a set of tools. Connect one and its tools become things XataWorks can do.
This is how you give the agent an ability it did not ship with. If your team runs a service with an API, if there is a server for the database you query every day, if the vendor of a system you use publishes one — connecting it means the agent can use it directly, rather than you pasting things between windows.
How this differs from a page tool
They can look similar in the chat and they are not alike.
| A page tool | A connection | |
|---|---|---|
| Comes from | A website you have open | A server you added |
| Exists while | That tab is open | The connection is enabled |
| Runs as | You, in your browser session | Whatever credentials the server itself holds |
| You control it by | Site permissions, per grant | Enabling, disabling or removing the connection |
The practical difference is durability and reach. A page tool is tied to a page you are looking at. A connection is always there, for every chat, until you turn it off — and it acts with its own credentials, not with your browser session.
What you can connect
Two shapes:
- A command — a program on your machine that XataWorks starts and talks to directly. The common case for tools that work with local files, a local database, or a command-line tool you already have installed.
- A URL — a server reachable over the network, which XataWorks talks to over HTTP.
Elsewhere — in a vendor’s setup instructions, or a colleague’s message — you may see these called by the name of the protocol they speak rather than by what they are. XataWorks calls them connections, because what matters to you is that something is connected and what it can do, not which protocol carried it.
Where they are managed
File ▸ Preferences…, then the Connections section under Integrations. Everything connected, and everything you could connect, is there.
What a row tells you
- Status — connected and its tools are available; disconnected and they are not; failed, with the reason shown. The reason is the useful part.
- Tool count — how many tools this connection is contributing right now. A connection that is connected but contributes nothing is worth a look: usually it started but is not configured.
- Authentication — whether credentials are set. A stored secret is shown as configured, never as a value, and is never pre-filled back into a form.
From here you can add a connection, edit one, sign in to one, enable or disable one without deleting it, and remove one.
Two kinds of row
Some connections you can change and some you cannot. Yours — anything you added — are fully editable. Ones XataWorks ships are declared by whoever built the application; they connect on their own and cannot be edited or removed here. If one of those is in your way, the reason on the row is what to pass on to whoever maintains your build: it names the problem precisely, which is exactly what they need.
When one will not connect
A failed connection tells you why, and the reason on the row is usually the whole answer.
| What it says | What it usually means |
|---|---|
| The program was not found | For a command: the path is wrong, the program is not installed, or it needs a runtime that is not on the application’s path. Run the exact command in a terminal; if it works there and not here, use an absolute path. |
| The program started and then stopped | It ran and exited — usually missing something it needed: a configuration file, an environment variable, an argument. Run it yourself and read what it prints. |
| It is not a tool server | The command ran but did not speak the protocol. A command-line program is not automatically a tool server; check you were given the right command. |
| The address could not be reached | For a URL: check you can reach the host from this machine, on this network. A corporate server often needs a VPN. Check the path too — tool servers usually live at a specific one. |
| Not authorised | Credentials are missing, wrong, or expired. Expiry is the most common cause of a connection that worked yesterday. |
| Connected, but no tools | It started and offered nothing. Usually it is configured to do nothing yet — pointed at an empty workspace, or missing the setting that tells it what to work with. |
Narrowing it down
- Disable it, then enable it again. Transient failures clear.
- Run the command yourself, exactly as entered, in a terminal.
- Try with authentication set to none. If the failure changes, the problem is credentials; if it does not, the problem is reaching the server at all.
- Check the reason changed. After each attempt, re-read the row. A different reason is progress.
A blank credential field means “keep the stored one”. Clearing the box does not clear the credential. To replace a token, paste the new one; to remove one, use the control that removes it.
Approving what a connection does
A tool from a connection is confirmed the way anything else is: you are told which tool is about to run and what it will be called with, and you can allow this call, allow it for the session, or decline. The difference from a page tool is what it acts as — the server’s own credentials rather than your browser session — which is worth holding in mind when you decide.
Back to all user-guide articles.