> ## Documentation Index
> Fetch the complete documentation index at: https://squad.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Add an MCP server or an API key
> Connect a service that is not in the app catalog, with an MCP server or an API key, and choose which tools your agents get.
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](/docs/integrations).
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:
Click **+ Add MCP server**.
Paste the URL or the JSON config into **Server URL or JSON config**.
Check the name on each server card. You can change it.
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.
Click **Connect server**. If you pasted several servers, the button is **Connect** followed by the number of servers.
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
Click **+ Add custom integration**.
In **Integration name**, type the name of the service, for example `Acme CRM`.
In the first field row, type the field name, for example `API_KEY`, and its value.
To add more values, click **＋ Add field**.
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.
```text Ask your lead theme={null}
Add this MCP server for the squad: https://mcp.example.com/mcp
```
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](/docs/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:
| Section | What it shows |
| --------------------------- | -------------------------------------------------------------------------------------------------------- |
| **BUILT-IN** | **Computer use**, marked **Always on**. |
| **MCP SERVERS** | One card for each server, with a switch for the whole server and **Show tools** for single tools. |
| **RESEARCH & SCRAPE TOOLS** | The built-in research tools, in families, each with a switch. These are the only tools that use credits. |
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.
| Message | Cause | Fix |
| ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------- |
| "Paste an MCP server URL or its JSON config." | The field is empty. | Paste the URL or the config. |
| "That doesn't parse as JSON. Paste the server's URL or its JSON config block." | The text is neither a URL nor valid JSON. | Copy the config again, in full. |
| "Expected a JSON object describing the server." or "That config lists no servers." | The JSON has no server in it. | Paste the block that holds the server. |
| "that URL doesn't parse." | The URL is not valid. | Copy the URL again. |
| "the URL carries login credentials." | The URL has a user name or password in it. | Remove them from the URL. Put the key in a header or in the key field. |
| "the URL carries a key in its "\[name]" parameter" | The URL has a key in its query text. | Remove the key from the URL. Put it in a header or in the key field. |
| "the "\[flag]" argument carries a key" | A command-based server has a key in its arguments. | Pass the key in `env` instead. |
| "has both a url and a command — pick one." or "needs either a url (hosted server) or a command (local server)." | The server object is not complete. | Keep either the `url` or the `command`. |
| "That's \[app]'s server — connect it from its card in Settings → Integrations so its built-in safety rules apply." | The URL belongs to a Recommended app. | Connect the app from its card. |
| "“\[name]” is the name of a built-in integration. Rename your MCP server and try again." or "That name is taken by a built-in integration." | The name belongs to a Recommended app. | Change the name on the server card. |
| "Fill in \[server]: \[field] — the server can’t authenticate without it." | The config asks for a value that is empty. | Type the value in the field on the card. |
| "Your workspace is still updating — signed-in MCP servers unlock shortly." | Your workspace computer does not support sign-in servers yet. | Try again later. |
| "Couldn’t check the server. Try again." or "Couldn’t connect. Try again." | Squad could not reach the server. | Check the URL, then try again. |
### Messages after a sign-in
The sign-in tab and the server card can show:
| Message | Cause | Fix |
| ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
| **Sign-in refused** and "The server didn't approve access" | You, or the server, turned down the approval. | Start again with **+ Add MCP server**. |
| "The sign-in finished in a browser tab that's signed out of Squad. Sign in there, then start the connect again." | The tab where you approved is not signed in to Squad. | Sign in to Squad in that browser, then add the server again. |
| **This sign-in has no connection waiting** | The window that started the sign-in was closed. | Start again with **+ Add MCP server**. |
| **Couldn't finish the connection** | The sign-in or the save did not finish. | Start again with **+ Add MCP server**. |
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
| Message | Fix |
| ---------------------------------- | ------------------------------ |
| "Couldn’t save that credential." | Open **Edit** and save again. |
| "Couldn’t delete that credential." | Click **Delete** again. |
| "Couldn’t rename that server." | Try the new name again. |
| "Couldn’t save the tool changes." | Open **Tools** and save again. |
When a save lands but your workspace computer is still restarting, an amber notice says so. You do not need to save again.