Connect Model Context Protocol servers so your agent can borrow tools from external systems without writing an integration.
The Model Context Protocol is a standard way for a system to advertise the tools it offers. Connecting an MCP server to a project borrows those tools into your agent — you supply a URL and any credentials, and the agent gains the server's capabilities without you writing an integration.
Servers are configured per project under Tools and apply to the next message with no deploy. Adding, editing, or removing a server requires workspace owner permissions.
Select Add MCP server and enter a name, the server URL, and its transport. The name determines how the agent sees the server's tools, so keep it short and recognizable — Linear rather than Our Linear MCP integration.
Open Authentication and add the header pairs the server expects, such as Authorization with a bearer token. Values are encrypted before they are stored and never returned to a browser.
Saving connects to the server and lists the tools it advertises. Open the server to see them, and narrow the allowlist if you do not want all of them exposed.
Ask the agent to do something that needs one of the tools, then confirm the call in Logs. Each run records the tool names it invoked.
| Transport | Stored as | When to use |
|---|---|---|
| Streamable HTTP | http | The default, and what most current MCP servers implement |
| SSE | sse | Older servers that only expose a Server-Sent Events endpoint |
If you are unsure, try Streamable HTTP first. A transport mismatch surfaces as a connection error on the server row rather than a silent failure.
Every borrowed tool is namespaced with the server's slug, derived from its name:
mcp_{slug}_{toolName}A server named Linear exposing create_issue becomes mcp_linear_create_issue. The prefix does real work: it tells the agent which integration a tool belongs to, and it lets the runtime label results as untrusted data from that specific server. The mcp_ prefix is reserved, so no client tool can impersonate one.
Slugs are lowercase, non-alphanumeric characters become underscores, and the base is capped at 24 characters. Renaming a server does not change an existing slug.
Auth headers are the sensitive part of an MCP connection, and they are handled accordingly:
A server can carry up to 10 headers, with names up to 80 characters and values up to 2,048 characters.
Because values cannot be read back, keep credentials in your own secret manager as well. Rotating a token means replacing the header set here, not editing one value in place.
By default every tool a server advertises is available to the agent. Open a server and check only the tools you want to permit — an allowlist with nothing selected means "allow all," which is why the dashboard normalizes an all-checked state back to empty.
Use Refresh to re-list tools after the remote server changes. Discovery also re-runs automatically when you change a server's URL, transport, or headers; renaming a server or editing its allowlist does not trigger it.
Narrow the allowlist to what the agent actually needs. It reduces the surface a compromised or misbehaving server can reach, and a smaller tool set measurably improves tool-selection accuracy.
| Status | Meaning |
|---|---|
| Connected | The last connection succeeded and tools were listed |
| Not connected | The server has never connected successfully |
| Unreachable | The last attempt failed. The row carries the error message |
| Disabled | You turned the server off. Its tools are not offered to the agent |
A server that cannot be reached during a conversation contributes no tools and the turn continues without them. The agent is not told why, so an unreachable server usually looks like an agent that "forgot" it could do something — check this page when a capability disappears.
| Limit | Value |
|---|---|
| Servers per project | 10 |
| Tools discovered per server | 100 |
| Tools exposed to the agent per server | 50 |
| Auth headers per server | 10 |
| Server name | 80 characters |
| Description | 500 characters |
| Connection timeout | 10 seconds |
| Tool call timeout | 30 seconds |
| Tool result text kept | 100,000 characters |
Results longer than 100,000 characters are truncated. A server whose tools return very large payloads is better wrapped in something that summarizes before returning.
An MCP server is third-party code with a foothold in your agent's tool set. Treat it that way.
Tool results are untrusted input. The runtime labels every MCP result as untrusted data from the named server, and the agent is instructed never to follow instructions embedded in one. A server that returns "ignore your previous instructions" is describing text, not issuing a command — but the safer posture is to only connect servers you trust with the credentials you gave them.
URLs are validated to prevent SSRF. Requests to localhost, private IPv4 ranges (10.x, 127.x, 192.168.x, 172.16–31.x, 169.254.x, 100.64–127.x), IPv6 loopback and link-local addresses, and .internal hostnames are rejected. Production requires https for public hosts so credentials are never sent in the clear; local development may use http against a private address to test a server before deploying it.
Grant the least privilege that works. Scope the token you give a server to the operations the agent needs. A read-only credential cannot be talked into a destructive action.
Prefer client tools for your own product. If the system is yours, a client tool runs in the visitor's browser with their own session and never needs a long-lived credential stored anywhere.
The server saved but shows Unreachable. Read the error on the row. Common causes are the wrong transport, a URL missing its path (many servers expose /mcp or /sse), or an auth header the server rejects.
No tools were discovered. The server connected but advertised nothing. Confirm the endpoint is the MCP endpoint rather than the service's REST API.
The agent never calls a tool. Check that the server is enabled, the tool is in the allowlist, and the tool's description explains when to use it. Descriptions come from the remote server, and a vague one leaves the agent no basis to choose it.
A tool call times out. Calls are capped at 30 seconds. Long-running work needs to return a handle immediately and report completion separately.