Get started · 03
How Tuxedo works
A Suit is one MCP server that your client connects to. This page follows a request from your agent through the Suit to your Connection's server and back: what the agent sees, what Tuxedo checks and counts on the way, and what it writes down.
Your Suit's endpoint
Each Suit has its own address: https://tuxedo.bot/mcp/ and the Suit's id, 20 random lowercase letters and digits. The Suit's page shows it, ready to copy. Renaming the Suit keeps the address.
In Signed URL mode, the address your client adds also carries the Suit's signature, ?v=…&signature=…, so the address itself is the credential.
The Suit's setup steps add it to your client under a name of its own, such as tuxedo-code-reviewer for a Suit called Code reviewer. Tuxedo makes it from the Suit's name when you create the Suit, and renaming the Suit doesn't change it.
What an agent sees
When a client connects, the Suit introduces itself as Tuxedo: Code reviewer, with the Suit's current name. It also sends instructions for the agent, which say, in this order:
- how its tools are named: “Tools from the "Code reviewer" Suit in Tuxedo. Each tool's name starts with the handle of the Connection it belongs to and two underscores: github__search_issues is the search_issues tool of the Connection with the handle github.”
- the Suit's description, if you gave it one, such as “Reviews pull requests for the web team.”
- under
Connections:, one line for each Connection: its handle and its name, then, when Tuxedo knows them, the account it signed in as and what you entered as Use this account for. For example:- github: GitHub · octocat — use for: workor- linear: Linear - for each GitHub Connection that signs in through this Tuxedo's GitHub App, a line saying its private repositories depend on the account it signed in as and on where the tuxedo-mcp app is installed, with the Connection's page in Tuxedo, so the agent can send you there when a repository it expects is missing
The instructions are kept to 2,048 characters; when they would be longer, Tuxedo shortens them, leaving out the GitHub lines first, then shortening the “use for” notes.
A Suit offers its tools, and nothing else.
Tool names
An agent sees each tool as the Connection's handle, __ and the tool's name on its server: github__search_issues. A handle is only lowercase letters, digits and dashes, so the first __ always ends it.
Apart from its name, each tool is listed as its server defines it, with one exception, below. Tuxedo leaves out a tool whose name the MCP specification doesn't allow.
Two accounts of one service
When a Suit includes two Connections of the same service, such as a work and a personal GitHub account, the description of each of their tools starts with “From” and the account: From GitHub · octocat — use for: work. The instructions add: “Some of its Connections are accounts of the same service: their tools' descriptions start with "From" and the account, so use the account the task is for.” A Connection's service is its server from the catalog, or for a custom server, the host in its URL. A Suit with one account of a service passes its descriptions on unchanged.
Only tools that are on are listed
When an agent asks a Suit for its tools, it gets only the ones that are on. When a Connection joins a Suit, all its tools start on. Tools explains the switches.
A tool that is off and a tool the Suit doesn't have get the same error: Tool [github__merge_pull_request] not found. So the agent can't tell a tool you switched off from one that doesn't exist.
Tuxedo checks the switch on every call, so a change counts from the agent's next request. It doesn't tell clients when you switch a tool, though, so a client may still have the list it fetched before. A tool you switched off is refused all the same. If a tool you switched on doesn't show up, do as the Suit's setup says: restart the client, and check that it lists the Suit's tools.
How clients sign in to a Suit
A Suit accepts only its current access mode:
- OAuth: a sign-in Tuxedo gave the client after you approved it for this Suit. A client approved for another Suit can't use it, even another of yours.
- Bearer token: one of the Suit's tokens, sent as
Authorization: Bearer txd_… - Signed URL: the Suit's signed URL, and only the current one. Once you rotate it, the old URL stops working.
A credential of another mode is refused: once a Suit switches to a signed URL its tokens stop working, and the other way round. A refused request gets HTTP 401 with a message saying how to sign in to this Suit, such as “Unauthorized: sign in to Tuxedo to use this Suit. MCP clients start signing in from this response, and the Suit's owner approves the client in Tuxedo.” Access compares the modes.
What happens on a tool call
-
1
Tuxedo checks the credential
As the Suit's access mode asks, above.
-
2
It counts the request
Toward the credential's requests for the minute.
-
3
It finds the tool
By its name, in the Suit. If the tool is off or unknown, or the call has no name or its arguments aren't an object, Tuxedo refuses it here.
-
4
It checks the week's tool calls
On Free only: the account must have tool calls left this week.
-
5
It calls the server, as you
Tuxedo signs in to the Connection's server with the Connection's credentials (or without signing in, for a server that needs none) and sends the call with the arguments exactly as your agent sent them.
-
6
The result goes back
As the server sent it, with only the protocol details Tuxedo's own server puts on every result: the result type, any caching hints, and Tuxedo's own server details in place of the server's.
-
7
Activity records the call
If the call can't get through, or the server asks for more input before it answers, which Tuxedo doesn't support yet, the agent gets Tuxedo's own message saying why instead, such as “Tuxedo could not call github__search_issues on GitHub. The server took too long to answer, so Tuxedo stopped waiting.”
Limits
Requests a minute
Each credential may send a Suit 120 requests a minute, on every plan. After that, requests get HTTP 429 for the rest of the minute. Every request counts, whether it connects, lists or calls. Each token has its own count, and so does each connected app and each signed URL, so a rotated URL starts afresh.
Waiting for a server
Tuxedo waits up to 10 seconds to reach a Connection's server and start talking to it, and a whole call takes at most 55 seconds, that included. After that, the call ends as Timed out.
Tool calls a week
On Free, an account can make 2,000 tool calls a week, across all its Suits. The week starts on Monday at 00:00 Philippine time.
- Counts: every tool call Tuxedo sends to a server, whether it then succeeds or fails.
- Doesn't count: listing tools, a call Tuxedo refuses, a request the per-minute limit stops, and a call Tuxedo can't send, such as when it isn't signed in to the server.
When the week's calls are used up, Tuxedo doesn't send the call, and Activity shows it as Weekly limit. The agent gets:
Pro has no weekly limit, but Tuxedo still counts its calls, for the meter on the Billing page. If Pro ends during a week, the calls made on Pro count toward Free's limit for the rest of it. Plans and billing has the rest.
When a Connection needs sign-in
A Suit still lists the tools of a Connection that needs sign-in. When the agent calls one and Tuxedo can't sign in, the agent gets an error that asks it to send you to reconnect:
For a Connection that signs in with OAuth, the link starts signing in again; for any other, it opens the Connection's page. The call shows in Activity as Needs sign-in. When a Connection needs you covers the fixes.
Keeping tool lists fresh
Tuxedo keeps a copy of each Connection's tools, and a Suit lists from that copy as it is. Tuxedo refreshes the copy in the background:
- every day, for every Connection
- when a Suit lists tools from a copy more than 6 hours old, at most once in 6 hours for each Connection
- when a server says it doesn't know a tool Tuxedo called
You can refresh a Connection yourself with Refresh tools on its page. Your switches are kept by the tool's name, so they stay through a refresh.
What Activity records
Every tool call that gets past a Suit's sign-in, the per-minute limit and the protocol's own checks writes one entry in Activity, including those Tuxedo then refuses. An entry records:
- when it happened, and how long it took
- the Suit and the Connection
- the name the agent called, and the tool's own name on its server
- how it ended: OK, Error, Refused, Timed out, Needs sign-in or Weekly limit
- how the client signed in, and the name its token or app carries (a signed URL carries none)
Tuxedo never stores a call's arguments or results. Connecting and listing tools aren't recorded.
Entries are deleted once a day after they're 1 day old on Free, or 7 days old on Pro. Deleting a Suit or a Connection keeps its entries, which then show “Deleted Suit” or “Deleted Connection”. Activity shows how to read them.