Skip to main content
Use Custom integrations when a service is not in the app catalog. You can add it in two ways:
  • An MCP server. Your teammates get every tool that the server exposes.
  • A custom integration. You store an API key or other values, and your teammates use them by name.
Only the owner and Administrators who are not limited to some teammates see Custom integrations and can change it. An Administrator sees the names and the field names, but not the saved values. To open it, click Settings at the bottom of the sidebar, then Apps, and select Custom integrations in the switch at the top of the page. You can also type “secret”, “api key”, or “env” in Find a setting in Settings. Old links to Settings > Secrets open this view. For apps in the catalog, see Connect apps. The view starts with two cards, Add MCP server and Add custom integration. The Add MCP server card says “Like ChatGPT and Claude connectors”: what ChatGPT and Claude call a connector is a hosted MCP server, and its address pastes in here. Below them, Your custom integrations lists each integration in its own card, with the number added. With none added, it says “No custom integrations yet”.
MCP servers and custom integrations do not use credits.

Add an MCP server

The Server URL or JSON config field accepts these formats:
  • A hosted server URL that starts with https://.
  • A single server object in JSON.
  • A client config block with mcpServers or servers, as MCP clients use. One block can hold several servers.
  • One entry copied from such a block, in the form "name": { ... }. A trailing comma is accepted.
A config can describe a hosted server (a URL) or a command-based server (a command and args). When you select Connect for a plugin’s server on the Skills screen, this window opens with the server already pasted. Each value that the plugin leaves to you, such as ${API_KEY}, shows as a field to fill in, and a plugin’s Authorization: Bearer ${KEY} header becomes the key field. See Connect a plugin’s MCP servers. Squad does not accept these:
  • URLs that start with http://. The error is “MCP server URLs must start with https://”.
  • SSE servers, for example a URL that ends in /sse. Use the vendor’s Streamable HTTP endpoint instead, which is usually the /mcp URL.
  • The URL or the name of a Recommended app, such as SiteGPT or Revid. Connect those from their card in the catalog, so that their protections apply.
To add the server:
1

Open the form

Click the Add MCP server card. The Add MCP server window opens.
2

Paste the server

Paste the URL or the JSON config into Server URL or JSON config.
3

Check the name

Check the name on each server card. You can change it. The card shows hosted for a URL or command for a command-based server.
4

Enter a key if you have one

If the server gave you a key, type it in the key field. For a bare URL, the field is Authorization: Bearer and it is optional.
5

Connect

Click Connect server. If you pasted several servers, the button shows the number, for example Connect 2 servers.
6

Sign in if asked

If the card shows Open sign-in page, click it, and approve access in the new tab. The connection finishes by itself. A server that builds its approval page from what Squad sends shows Squad’s name and logo.
Leave the key field empty for public servers and for servers that sign you in. Squad finds out by itself that a server uses a sign-in page. On Squad for Mac, a server that signs in through a sign-in page opens that page in your browser. The window says “Finish signing in in your browser. Squad waits up to 5 minutes, then you can try again.”, with Cancel sign-in. When the server’s sign-in cannot come back to the Mac, the window says “This server signs in through your browser, and that sign-in finishes on squad.so. Add it from Squad on the web; it shows up here as soon as it’s connected.”, with Open Squad on the web.

Check that it works

  • The card shows Connected and the window closes.
  • The server shows under Your custom integrations in its own card, with an MCP tag, its address, and an on and off switch.
  • Click Tools on the server’s card. When you save a server, Squad asks it for its tools right away, so the list is usually ready at once. The list shows each tool as the server name, an underscore, and the tool name. For example, a server named “Acme CRM” gives tools that start with acme_crm_.
The window’s footer says “Its tools show here once it’s saved.” If the list says “No tools to show yet. They show here once the server lists them.”, Squad could not get the tools when you saved, for example because the server did not answer in time. Send a teammate a message, then open the list again. On Squad for Mac, the footer says “Tools show on the server’s card once it’s saved.” For the wait, see Limits and defaults.

Connect a second account of the same server

Each server name is one account. If you add the same server again with the same name, Squad updates the credentials of the existing entry. The card warns you with “Already connected as” followed by the name. To add a second account:
  1. On the server’s card, click Add account.
  2. Keep the suggested name, or type a different name.
  3. Click Connect server, and sign in or enter the key for the other account.
The second account gets its own tool names, from its own name. The accounts of one server share one card, which shows the number of accounts. Each account is a row in it with its own Tools, Edit, Delete, and switch. A Recommended app, such as SiteGPT, has no Add account.

Renew a sign-in

Most servers that you connected with a sign-in page renew their access by themselves. Some services keep Squad signed in for a limited time and do not let Squad renew it. When you connect such a server, Squad says so, for example ”“[name]” keeps Squad signed in for about [time], and doesn’t let Squad renew that on its own. After that, its tools stop working until you sign in to it again here. If it gives you an access token that doesn’t expire, connecting with that keeps it working.” When a server turns down your sign-in, its card says so. The owner selects Sign in again on the card. See A server turns down its credential.

A server turns down its credential

When a server refuses the key or the sign-in that Squad saved for it, its card, or the account’s row, shows a dot and one of these lines:
  • “[name] turned down the saved credential, so your teammates can’t use it. Save a new one with Edit.” Select Edit and save a key that the server accepts.
  • “[name] turned down your sign-in, so your teammates can’t use it.” The owner selects Sign in again. The card then says “Approve access on the server’s sign-in page. This card updates by itself once you do.” with Open sign-in page and Start over. If the sign-in page is no longer valid, the card says “That sign-in page expired. Sign in again to start a new one.”
Only the owner also sees what the server said, after “It said:”. When the server gives a short title and a reason, both show, for example “Unauthorized Access: Admin system user tokens are not permitted on the Ads MCP server. Please use an Employee system user token.” An Administrator sees the line without it. For a sign-in, an Administrator reads “The squad’s owner can sign in to it again.” instead of Sign in again. On Squad for Mac, Sign in again opens the server’s sign-in page in your browser, and Cancel sign-in stops the wait. If the Mac cannot do the sign-in, it says “[name] can’t be signed in again from this Mac yet. Sign in again at squad.so.” An Administrator reads “[name] turned down its sign-in, so your teammates can’t use it. Ask [owner] to sign in to it again.” After a refused sign-in, Tools on the Mac says “These work again once you save a credential the server accepts.” While the server refuses, Tools on the card still lists the tools that it listed before, with “These work again once you save a credential the server accepts.” or “These work once you sign in again.” When you save a new credential, the line goes away, and Squad asks the server for its tools right away. If the server turns down the new credential too, the line comes back with what the server said.

Add a custom integration with an API key

1

Open the form

Click the Add custom integration card. The New custom integration window opens.
2

Name the integration

In Integration name, type the name of the service, for example Acme CRM.
3

Add the first field

In the first field row, type the field name, for example API_KEY, and its value.
4

Add more fields

To add more values, click Add field.
5

Save

Click Add custom integration.
Each field becomes an environment name made from the integration name and the field name. For example, the name Acme CRM and the field API_KEY give ACME_CRM_API_KEY. The window says “Your teammates refer to these fields by name.” Squad stores the values on your cloud computer. The card shows each field’s full name with the value hidden, for example ACME_CRM_API_KEY · ••••. When the owner clicks Edit, the Edit custom integration window shows the current saved values as dots. To read a value, click the eye beside it (Show value). Click it again (Hide value) to hide it. When the owner clicks Save changes, the button says Saving… and the window stays open until the save is done:
  • Squad writes only what you changed in the window. A value that you edited is saved. A field that you emptied or removed is deleted, as long as at least one other field keeps a value. If you empty every field, the window says “Add at least one field with a value.” and nothing changes. To remove the whole integration, use Delete on its card.
  • Every other field keeps the value that is saved at that moment. So a key that someone changed elsewhere while your window was open is kept.
  • A field that an MCP server’s sign-in headers use cannot be emptied. The window says “The server signs in with [field], so it needs a value.” This does not cover fields that a server started with a command reads, for example an API_KEY field: you can empty those.
  • If the save fails, the window stays open with what you typed and says why, for example “Couldn’t save that credential.” or “Couldn’t check the saved values, so nothing was changed. Try again.” Click Save changes again.
On Squad for Mac, the editor shows the values as dots with the same eye, and a save keeps the same fields. Edit on an MCP server opens Edit credential, where you can change the name and the values of its fields. The field names stay fixed, because the server’s config refers to them. For a server that you connected with a sign-in page, Edit opens Sign-in connection, where only the name can change, with Save name. With many custom integrations, Find an integration shows above the list. It finds one by its name, what it is for, a field name, or its address, never by a saved value. The count then says, for example, “3 of 21”. With no match, it says “Nothing matches” and your words. To empty the field, select the x (Clear the search). See Limits and defaults. When a question asks you to connect an app that is not in the app catalog, Connect and the app’s name opens a new custom integration with that name filled in. See Know the ask types. On Squad for Mac, the list shows at once what your cloud computer last listed, and checks again beside the heading. On the web, the list is read fresh each time you open it. On the Mac, the owner and Administrators can use Connect on such a question. Delete opens a dialog, “Delete [name] for good?”, that says “Your teammates lose access to it. To connect it again, you enter its values again.” Click Delete to remove it.

Let a teammate add a server from chat

A teammate can also list the names of your custom integrations and keys. For the owner and Administrators who can see every teammate, it can rename one, delete one, and switch an MCP server on or off. It never sees or types a saved value. A deleted server’s tools stop once no teammate is working. See Skills, tools, and saved logins. You can paste an MCP server URL or JSON config into chat and ask a teammate to add it. The teammate adds it the same way as the dashboard does, and your teammates can use its tools from their next run.
Ask your lead
Limits when you paste a server in chat:
  • A server that signs in with a sign-in page cannot connect this way. The teammate asks you to add it under Settings > Apps > Custom integrations with Add MCP server.
  • If a config refers to a key without a value, the teammate asks you for the value or asks you to add the credential under Custom integrations.
A teammate can also propose a server with a chat card. The card shows An app connection to add, the server name and URL, an Add server button, and Not now. Add server saves the server. If the server needs a sign-in, a new tab opens for it. After it is added, the card shows Open in Apps, which opens Custom integrations. When a teammate needs a key, it sends a card titled A key to add. Type the value into the card and click Save to vault. The card saves the value to your cloud computer. The value is not posted as a chat message. Do not paste keys as plain chat messages.

Servers that keep a session

Some MCP servers keep state on their session, for example a sign-in that you complete through one of the server’s tools. For a server that you add by URL, Squad keeps one session for each connected server across runs and restarts of your cloud computer, so such a sign-in holds. When you change the server’s URL, its headers, or its key, Squad starts a new session. A server that runs as a command starts fresh for each tool call, so a sign-in on it does not hold.

Turn tools on or off

Every tool rides along on every model request. Turn off tools that you do not use to keep requests small. Some AI providers, for example Grok, limit the number of tools in a request. For the number, see Limits and defaults. You turn tools off on the server’s card under Custom integrations. Links to the old Tools page open Custom integrations. Research tools, the built-in tools that use credits, are switched on Billing. See Turn research tools off.
  • Each MCP server’s card has an on and off switch for the whole server. The switch moves once your cloud computer has the change. To turn single tools off, click Tools on the card. The list says “Your teammates can call these. Untick one to turn it off.” Clear the tools that you do not want, then click Save tools. More on a tool shows its full description, its parameters with their types, and Full schema (JSON). Nothing restarts. A tool that you turn off is gone from your teammates’ next runs, and a run that is going cannot call it again.
  • The switches apply to the whole squad. They do not set tools for each teammate.
Some tools show Always off in the server’s tool list. Squad keeps them off to protect your accounts, for example the Revid tool that buys credit packs. You cannot turn them on. If such a tool is not off yet on your cloud computer, the tool list says “Save to turn off” and the tool’s name, “This integration always keeps it off.” Click Save tools. Saving tools does not restart anything, so you can save while your teammates work. Each teammate’s next run uses the new tools. The core Squad tools and computer use have no switch. They are always on.

Troubleshooting

The error “MCP server URLs must start with https://” shows. Cause: the URL uses http://. Fix: use the vendor’s https:// URL. The error says the server is an SSE-transport server. Cause: Squad does not support SSE servers. Fix: paste the vendor’s Streamable HTTP endpoint, usually the URL that ends in /mcp. The error says the name is the name of a built-in integration, or that the URL is a Recommended app’s server. Cause: the server belongs to a Recommended app. Fix: connect it from its card in the catalog under Connected apps. The error says command-based MCP servers and custom headers unlock shortly. Cause: your cloud computer is still updating. Fix: use a plain https:// URL now, or try again later. The server connected, but no tools show. Cause: Squad asks a new server for its tools when you save it, and the server did not answer in time, or your cloud computer could not ask it yet. Then the tools show the first time a teammate runs. Fix: send a teammate a message. After the teammate has worked, click Tools on the server’s card again. The error says “Two servers collapse to the same name”. Cause: two servers in the config give the same name. Fix: rename one of them in the config and paste it again.

Messages when you paste a server

Most messages start with the server name in quotes.

Messages after a sign-in

The sign-in tab and the server card can show: After a successful sign-in, the tab says “Your server is set up and its tools reach your agents within a couple of minutes.” It closes by itself after a moment. If it shows a note, read it, then click Back to Squad.

Messages on the list

A save on this list applies without a restart. If your cloud computer has not applied it yet, an amber notice says so, for example “Saved. Your squad is still applying the change, which takes about a minute.” You do not need to save again.