Connections · 04
When a Connection needs you
Tuxedo keeps a copy of each Connection's tools and asks its server for them again as it goes. When a server stops letting Tuxedo in, or stops answering, the Connection's status says so, and every Suit that wears it shows the problem. This page explains what each status means, where you'll see it, and how to put it right.
The four statuses
Every Connection has a status. It shows beside the Connection's name on its page, and in the Status column on the Connections page.
- Pending Saved, but its tools haven't loaded yet.
- Connected The tools loaded at the last refresh.
- Needs sign-in The server refused Tuxedo's sign-in, or Tuxedo isn't signed in.
- Error The last refresh failed another way: for example, the server took too long, couldn't be reached, or didn't answer like an MCP server.
A Connection you add with OAuth shows Needs sign-in until you finish signing in on the service's own page.
A Connection that needs you keeps its tools
Where Tuxedo tells you
Needs sign-in and Error are the two statuses that need you. Every place below works the problem out the same way, so they always agree.
- The sidebar. Connections shows an amber dot and how many need you. Above your plan, the Action required card shows the first of them, with its fix as the button. When there are more, it links to the rest.
- The Connections page. The Connection's row turns amber for Needs sign-in or red for Error, with the reason under its name.
- Your Suits. On the Suits page, a Suit's card shows its first problem in place of its last call, with that problem's fix and how many more there are. Every page of the Suit shows a callout for each problem at the top.
- The Connection's page. An OAuth Connection that needs sign-in has a Sign in to use this Connection banner with Reconnect. Any other problem shows Tuxedo couldn't load this Connection's tools with the reason.
A problem reads “Notion needs sign-in” or “Linear has an error”. The Connections page, a Suit's callouts and the Connection's page add the reason, the error Tuxedo last recorded, in its own words, such as “The server refused the credentials Tuxedo sent (HTTP 401).” or “The server took too long to answer, so Tuxedo stopped waiting.”
What it costs
When any of the Connection's tools are on in a Suit, the Action required card and the Connection's banner count them, naming each Suit: “9 tools in Research are unavailable.” Those tools stay listed in your Suits all the same.
Reconnect or Open
Each problem's fix is one of two buttons.
- Reconnect is for a Connection that signs in with OAuth and needs sign-in. It takes you straight to the service's own sign-in page.
- Open is for everything else. It opens the Connection's page, where you can replace a token or a custom server's sign-in, or refresh the tools.
The Action required card and a Suit's callouts name the Connection on the button, as in Reconnect Notion or Open Linear. On the Connections page, a Connection to reconnect has Reconnect on its row; every other row has Open and Refresh tools in its … menu.
Signing in again
Approve Tuxedo on the service's page to sign the Connection in again; Tuxedo then refreshes its tools. If you don't approve it, Tuxedo says “You didn't approve Tuxedo, so it isn't signed in.” and the Connection stays as it was.
Reconnect appears only while an OAuth Connection needs sign-in; there's no button to sign in again otherwise. To use another account of the same service, connect the service again: it becomes a Connection of its own, with its own handle.
Replacing a token
A Connection you connected with Your own token has a Token card on its page. When the service stops accepting the token, because it expired or you revoked it, replace it there:
-
1
Create a new token on the service
The card's Create a token on … link goes to the service.
-
2
Paste it into New token
Tuxedo stores it encrypted, and never shows the current token.
-
3
Choose Replace token and reload tools
Tuxedo saves the token and refreshes the tools with it.
A custom server that signs in with a header is fixed the same way, in its Server and sign-in card: enter the New header value and save. Custom servers explains that card.
A catalog Connection whose sign-in shows as No auth has no sign-in to replace, so if its server starts asking for one, its page has no way to give it.
When it's an error
Read the reason on the Connection's page. Once the server is answering again, choose Refresh tools. If the trouble was on the server's side, you may not need to: Tuxedo keeps refreshing by itself, and the first refresh that loads the tools sets the Connection back to Connected.
Staying signed in
When you sign in with OAuth, the service gives Tuxedo an access token, and usually says when it expires and gives a refresh token to renew it. Before Tuxedo uses an access token, it renews it if that expiry has passed or is about to, and keeps the new one. You don't see this happen.
A renewal turns into Needs sign-in when the service refuses it, for example because the refresh token expired or was revoked, or when the service gave Tuxedo no refresh token. Tuxedo then forgets the sign-in and records “The sign-in expired and the server didn't renew it. Reconnect to sign in again.”
If the service's sign-in doesn't answer, fails on its side or asks Tuxedo to wait, Tuxedo keeps the sign-in and tries again the next time it needs the token. A refresh that runs into this shows Error, with the reason “Tuxedo couldn't renew the sign-in: the server's sign-in service didn't answer properly. Try again in a moment.”
Tuxedo doesn't renew a token you pasted, a header value, or an OAuth token whose expiry the service didn't give.
Refreshing tools
Refresh tools asks the server for its tools again. It's on every Connection's page, and in the … menu on the Connections page.
It refreshes this one account only. If you've connected the same service more than once, each account keeps its own tools and its own Refresh tools, and Tuxedo's message after a refresh names the accounts it left alone. Two Connections are the same service when they come from the same server in the catalog or, for custom servers, when their URLs have the same host.
- When it works, Tuxedo says how many tools it loaded, and the Connection is Connected.
- When it fails, Tuxedo keeps the tools it had, and the status and the reason say why.
- Tools are matched by name, and ones the server no longer lists go.
- Each tool's switch in a Suit is kept by tool name, so a refresh doesn't change it. Tools explains how the tools a refresh adds start.
Last refreshed on the Connection's page says when its tools last loaded. On the Connections page, the … menu says it too, or Tools never loaded.
Refreshes Tuxedo runs by itself
- Every day, for every Connection.
- When a client lists a Suit's tools and one of the Suit's Connections last loaded its tools more than 6 hours ago, or never has. Tuxedo answers with the tools it has, then refreshes that Connection in the background, so the client never waits. It does this at most once every 6 hours for each Connection.
- When a server says it doesn't know a tool an agent called.
The Tools tab
A Connection's page has two tabs, Overview and Tools, the second with its count. It shows what Tuxedo last managed to load from the server. You don't switch anything here: you switch tools on and off in each Suit.
The Tools tab lists each tool with its description and four hint columns, Read-only, Destructive, Idempotent and Open-world, each Yes, No or Not stated. The server declares these hints about its own tools, and Tuxedo shows them as declared, without checking them:
- Read-only: the tool doesn't change anything.
- Destructive: it may delete or overwrite, rather than only add.
- Idempotent: calling it again with the same arguments has no further effect.
- Open-world: it reaches beyond the service, as a web search does.
Read-only matters most: a Suit's Tools page groups tools by risk, read-only first. Choose a tool's name to see its parameters, which of your Suits have it on, and its recent calls.
Used in Suits
The Used in Suits card on a Connection's page lists the Suits that wear it and, when the Connection has tools, how many are on in each, such as “3 of 12 tools on”; choose the count to go to that Suit's tools.
Add to a Suit lists your Suits that don't wear it yet. Choose one and it's added at once, with all its tools on. When every Suit already wears it, the card says so, and when you have no Suits, it offers Create a Suit.
Deleting a Connection
Delete connection is on every Connection's page. Tuxedo asks first, and lists the Suits the Connection will be taken out of. Deleting it:
- removes the Connection, its stored credentials and its tools from Tuxedo;
- takes it out of every Suit that wears it, along with its tools' switches there;
- keeps its Activity: its past calls stay in your log like any other entry, marked Deleted Connection.
It can't be undone. Its handle is free again, so a new Connection can take it. On Free, deleting one also makes room under the limit of 10 Connections; Plans and billing has the details.
Tuxedo doesn't tell the service