Docs Custom servers

Connections · 03

Custom servers

Any remote MCP server can be a Connection, not only the ones in the catalog. Give Tuxedo the server's URL and say how to sign in, and it loads the tools as soon as you save, or once you sign in.

Add a custom server

  1. Open the form

    On Connections, the last card under "Connect a server" (or "Add more", once you have a Connection) is "Custom server". Choose "Connect by URL" on it. When a search of the catalog finds nothing, the same button is under the empty result.

  2. Name the Connection

    "Name" is what you call the server in Tuxedo, up to 100 characters, and you can change it later. "Handle" is lowercase letters, digits and dashes, starting with a letter, at most 24 characters, and different from your other Connections' handles. Agents see each of the server's tools as handle__tool, so the handle can't change later.

    "Use this account for" is optional: a note of up to 200 characters that helps agents pick the right account when you connect a service more than once. For a custom server, the service is the URL's host, so two Connections to servers on one host are two accounts of the same service.

  3. Enter the server's URL

    "Server URL" is the server's MCP endpoint, up to 2,048 characters, such as https://mcp.example.com/mcp. The server's URL says what Tuxedo accepts.

  4. Choose how Tuxedo signs in, and save

    Choose "No auth", "Header" or "OAuth" under "Sign-in", then "Save and load tools", or "Save and sign in" for OAuth.

Once the tools load, Tuxedo opens the Connection's page and says how many it loaded. If you started from a Suit, Tuxedo adds the server to that Suit instead, with all its tools on, and takes you back to it.

A custom server is a Connection like any other, so it counts toward your plan: Free includes 10 Connections. Plans and billing compares the plans.

The server's URL

Tuxedo only talks to public servers over HTTPS. When you save, it checks the URL and says what's wrong if it can't use it:

  • It must use HTTPS. Another scheme, such as http://, gets "Only HTTPS URLs are allowed."
  • It can't hold a username or a password: "URLs must not contain a username or password."
  • Its host must be a host name or a public IP address, and every address a host name resolves to must be public. Tuxedo refuses private networks, loopback, link-local addresses (where cloud metadata services live) and other reserved ranges, with a message that names the host, such as "[intranet.example.com] resolves to a private or reserved address."

Tuxedo checks again before every request it sends to the server, not only when you save, and connects only to the addresses it checked.

Tuxedo never follows a redirect

Enter the URL of the MCP endpoint itself. If the server answers with a redirect, Tuxedo doesn't follow it, and the tools don't load.

How Tuxedo signs in

Under "Sign-in", choose one of three:

  • No auth: the server needs no sign-in.
  • Header: Tuxedo sends a header, such as an API key, with every request.
  • OAuth: you approve Tuxedo on the server's own sign-in page.

You can change the choice later, on the Connection's page: see Change the server or sign-in later.

Choose "Header" when the server takes an API key or a token in a header. Tuxedo sends that header with every request to the server.

  • "Header name" starts as Authorization. Change it if the server expects another, such as X-API-Key. It must be a valid HTTP header name of up to 64 characters.
  • Tuxedo adds nothing to "Header value", so include any prefix the server expects, such as Bearer before a token. It can be up to 4,096 characters, without line breaks or control characters other than tabs. Tuxedo stores it encrypted and never shows it again.

Tuxedo refuses the headers it sets itself: accept, connection, content-length, content-type, expect, host, keep-alive, proxy-authorization, te, trailer, transfer-encoding, upgrade, and any header that starts with mcp-, however you capitalise them.

If the server refuses the header, the Connection is still saved, and its page says why. Enter the right value under "Server and sign-in" on that page.

Sign in with OAuth

Choose "OAuth" when the server has its own sign-in page. "Save and sign in" saves the Connection as "Needs sign-in" and starts signing in: once you approve Tuxedo on the server's sign-in page, the server sends you back and Tuxedo loads the tools.

Which client Tuxedo signs in as

Tuxedo signs in as the first of these that applies:

  1. Your own OAuth app, when you entered its client ID.
  2. Tuxedo's client metadata document, when the server accepts one. Tuxedo's client ID is then the address of a document that describes it, https://tuxedo.bot/oauth/client-metadata.json. Tuxedo uses it only where it runs on a public HTTPS address.
  3. The client the server registered for this Connection at an earlier sign-in, while it is for the same authorization server and callback URL.
  4. Registering itself with the server, when the server allows it. Tuxedo keeps that client for the next sign-in.

When none applies, signing in can't start: "The server doesn't let Tuxedo register itself. Register an OAuth app on it and enter its client ID instead."

Your own OAuth app

For a server that doesn't let Tuxedo register itself, register an OAuth app on the server with this callback URL:

Callback URL
https://tuxedo.bot/oauth/callback

Then enter the app's "Client ID" and, if it has one, its "Client secret". Both are optional. The client ID can be up to 255 characters, without spaces or control characters; the secret up to 4,000 characters, without line breaks or other control characters, and Tuxedo stores it encrypted. Without a secret, Tuxedo signs in as a public client, protected by PKCE.

What the server must support

Tuxedo signs in the way the MCP authorization specification describes. It first asks the server for its tools without signing in, and reads how to sign in from the refusal. Then it finds the server's authorization server and checks it:

  • It is on HTTPS, and so is its sign-in page.
  • It supports PKCE with S256, which Tuxedo always uses. Otherwise Tuxedo says "The server's authorization server doesn't support PKCE with S256, which Tuxedo requires."
  • Its sign-in settings don't name another server, or another authorization server.

Tuxedo asks for the scopes the server's refusal names, or else every scope the server lists.

When signing in can't start, Tuxedo says "Tuxedo couldn't start signing in." and why, on the Connection's page (or on Connections, when you were adding it to a Suit). A server you just saved stays saved, as "Needs sign-in", with "Reconnect" on its page to try again. When a Connection needs you covers signing in again later.

When the server needs no sign-in

If you choose "OAuth" for a server that lets anyone list its tools, Tuxedo doesn't sign in. It says:

Tuxedo couldn't start signing in.

This server lets Tuxedo in without signing in, so it doesn't need OAuth. Choose No auth instead.

The Connection is saved all the same, as "Needs sign-in", and "Reconnect" fails the same way. Open the Connection, choose "No auth" under "Server and sign-in", and choose "Save and reload tools".

When the tools don't load

Tuxedo saves a custom server even when its tools don't load. The Connection then shows "Needs sign-in" or "Error", and its page gives the reason.

Fix the URL or the sign-in under "Server and sign-in", or choose "Refresh tools" once the server is back. If you were adding the server to a Suit, it isn't added until its tools load: you stay on Connections, with the reason.

Tools Tuxedo skips

Tuxedo skips a tool, without saying so, when its name has a space, a colon or an accented letter in it, or more than 128 letters, digits, _, . and -. A skipped tool doesn't count among the Connection's tools.

Change the server or sign-in later

Only a custom server's URL and sign-in can change. Open the Connection and use "Server and sign-in", which has the same three choices. A Connection from the catalog keeps the server it came with; Connect a server covers those.

A blank "New header value" or "Client secret" keeps the one stored, as long as the URL stays the same and, for the secret, the client ID does too. Saving reloads the tools, or sends you to sign in when the Connection signs in with OAuth and isn't signed in.

A new URL starts over

Tuxedo clears every stored credential and the old server's tools, so nothing meant for the old server reaches the new one.
  • Enter the header value again in the same save. Otherwise Tuxedo asks for it: "Enter the header value again. Tuxedo clears stored credentials when the URL changes."
  • For OAuth, saving sends you to sign in again. Your own app's client ID stays, but enter its client secret again in the same save. A client the server registered for Tuxedo is forgotten too.
  • The tools are loaded from the new server: when you save, or once you sign in.
  • Your Suits start afresh: once the new server's tools load, each Suit that includes the Connection has all of them on, whatever the Suit's new-tool policy.

Other changes clear only what no longer applies. Switching away from "Header" clears the header. Switching away from "OAuth" ends the sign-in and forgets your own app's client ID and secret. Changing your own app's client ID ends the sign-in, since its tokens belong to the old app.

The handle never changes. Rename the Connection, or change what it's for, under "Details".