Skip to main content
Use the Custom integrations tab when a service is not in the app catalog. You can add it in two ways:
  • An MCP server. Your agents get every tool that the server exposes.
  • A custom integration. You store an API key or other values, and your agents use them by name.
Both are on Integrations > Custom integrations. To open Integrations, click the grid icon (tooltip Integrations) in the strip at the bottom of the sidebar. For apps in the catalog, see Connect apps.
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). 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 + Add MCP server.
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.
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 is Connect followed by the number of 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.
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.

​
Check that it works

  • The card shows ✓ Connected and the window closes.
  • The server shows under YOUR CUSTOM INTEGRATIONS with an MCP tag.
  • After about a minute, click Tools on the server row. 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_.
If the list says “No tools to show yet”, wait a minute or two and open it again.

​
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 row, 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.

​
Renew a sign-in

Servers that you connected with a sign-in page renew their access by themselves. If a server stops working, add it again with the same address and approve the sign-in again.

​
Add a custom integration with an API key

1

Open the form

Click + Add custom integration.
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. Your agents use the fields by these names. Squad stores the values on your workspace computer. The list shows the field names with the values hidden. When you click Edit, the window shows the current saved values, and Save changes writes exactly what the fields show.
Delete on a row removes the integration at once. There is no confirmation step.

​
Let an agent add a server from chat

You can paste an MCP server URL or JSON config into chat and ask an agent to add it. The agent adds it the same way as the dashboard does, and the tools arrive within a minute or two.
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 agent asks you to add it on Integrations > Custom integrations with + Add MCP server.
  • If a config refers to a key without a value, the agent asks you for the value or asks you to add the credential on the Custom integrations tab.
An agent can also propose a server with a chat card. The card shows ADD MCP SERVER, 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 Manage in Tools →. When an agent needs a key, it sends a CREDENTIAL NEEDED card. Type the value into the card and click Save to vault. The card saves the value to your workspace computer. The value is not posted as a chat message. Do not paste keys as plain chat messages.

​
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 can turn tools off in two places:
  • For one server: on the Custom integrations tab, click Tools on the server row. Clear the tools that you do not want, then click Save tools. This applies through a restart of the agent software on your workspace computer, which takes about a minute.
  • On the Tools screen: click the Tools icon in the strip at the bottom of the sidebar, or open Settings > Tools.
The Tools screen applies to the whole workspace. It does not set tools for each agent. It has these sections: Some tools show always off on the Tools screen and protected 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. To save changes on the Tools screen, click Save changes in the bar at the bottom. Reset discards them.
Saving on the Tools screen restarts the agent software on your workspace computer. Save when your agents are not in the middle of work.
The core Squad tools are not on this screen. 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 on the Connected apps tab. The error says command-based MCP servers and custom headers unlock shortly. Cause: your workspace computer is still updating. Fix: use a plain https:// URL now, or try again later. The server connected, but no tools show. Cause: the workspace has not reloaded yet. Fix: wait a minute or two, then click Tools on the row 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

When a save lands but your workspace computer is still restarting, an amber notice says so. You do not need to save again.