MCP Servers
Overview
An MCP Server is an external service that speaks the Model Context Protocol and exposes a set of tools your agents can call — for example, Atlassian's Jira MCP, GitHub's MCP, a Datadog MCP, or any custom MCP server you've built or self-hosted.
Once a server is registered, the platform connects to it, discovers its tools, and makes them available for selection inside any agent's configuration.
MCP servers live under Automation → Custom Agents → MCP Servers.
Supported transports
The platform supports the two transports defined by the MCP spec:
| Transport ID | Label in UI | When to use |
|---|---|---|
streamable_http | Streamable HTTP — modern MCP standard | Preferred. Most current MCP servers. |
sse | SSE — Server-Sent Events (older servers) | Older or legacy MCP servers. |
The transport type controls how the platform talks to the server; the URL format depends on which one you pick. The form will show an example URL for the selected transport as a hint.
Authentication modes
The platform supports five authentication modes. The mode you pick determines which credential fields appear on the form.
| Auth type ID | Label in UI | What you provide |
|---|---|---|
none | None | No credentials. Only safe on trusted internal networks. |
bearer | Bearer token | A token sent as Authorization: Bearer …. |
basic | Basic Auth (username / password) | A username and password — sent as standard HTTP Basic. |
header | Custom headers | One or more arbitrary header pairs (e.g. X-API-Key: …). |
oauth_mcp | OAuth MCP | Full OAuth flow per the MCP Authorization spec — you supply no static credentials, the platform negotiates with the server. |
Credential values are encrypted at rest and never returned to the browser after save. Edit forms always show empty credential fields — leaving them blank means "keep the existing values"; entering new values replaces them.
Adding an MCP server
- Open Automation → Custom Agents → MCP Servers.
- Click New MCP server in the top-right of the list.
- Fill in the Connection card:
| Field | Required | Description |
|---|---|---|
| Server name | Yes | A friendly label, e.g. Atlassian Cloud. |
| Server URL | Yes | The MCP endpoint URL. Format depends on the transport — the form shows an example for the chosen transport. |
| Transport type | Yes | Streamable HTTP (modern) or SSE (older). Defaults to SSE. |
-
Fill in the Authentication card:
- Pick an Auth type.
- Provide credentials specific to that mode (see below).
-
(Optional) Adjust Timeouts & Retries — defaults are fine for most servers:
| Field | Default | Notes |
|---|---|---|
| Connection timeout (ms) | 30 000 | How long to wait for the initial connection. |
| Request timeout (ms) | 60 000 | How long to wait for a tool call to return. |
| Max retries | 3 | Range 0–10. Applies to transient failures. |
- Click Save server.
The platform will then attempt a handshake and discover the server's tools. The discovered tools are listed at the bottom of the server detail page (read-only at the server level — actual tool selection happens per-agent).
Authentication mode details
None
No credentials are sent. The platform shows a warning callout: "No authentication. Only use on trusted internal networks." This is appropriate for self-hosted MCP servers running on a private VPC.
Bearer token
Provide a single Token value. The platform sends it as
Authorization: Bearer <token> on every request. Most modern API-key
style MCP servers (OpenAI, Anthropic-aligned, GitHub PAT-based, etc.)
use this mode.
Basic Auth
Provide Username and Password. Both are required and are sent as a standard HTTP Basic header.
Custom headers
Provide one or more Header name / Value pairs. The form starts
with one empty pair and lets you add or remove additional rows. This
mode is useful when:
- The server expects a non-standard header name (e.g.
X-API-Key: …). - The server expects multiple headers — for example, Datadog
requires both
DD-API-KEYandDD-APPLICATION-KEY, which is exactly the case this mode is built for.
OAuth MCP
OAuth MCP is the flow defined by the MCP Authorization spec. Unlike the other modes, you do not supply any static credentials at create time. Instead:
- Pick OAuth MCP as the auth type and save the server.
- On the server detail page, an OAuth connection card appears showing Not connected.
- Click Connect. A popup opens to the provider's consent screen.
- The platform handles discovery, Dynamic Client Registration (DCR), and PKCE automatically — you don't paste a client ID, client secret, or redirect URL anywhere.
- Once you approve in the popup, the popup closes itself and the server card switches to Connected with the token's expiry date.
- Token refresh is fully transparent and happens server-side; the UI simply continues to show Connected as long as the refresh token is still valid.
If the provider revokes consent or the refresh token expires, the card switches to Re-authorization required and you can click Reconnect to redo the consent flow.
To remove access, click Disconnect. A confirmation dialog warns that "Your tokens will be revoked. Workflows using this server will fail until you reconnect." — accept and the row's status drops back to Not connected.
Per-user OAuth tokens. OAuth MCP tokens are scoped to the individual user who connected, not to the organisation. Each user who wants to run an agent that uses this server must connect themselves. At runtime, the agent uses the calling user's token automatically.
Tool discovery
When you save a new server (or change its URL/credentials on an existing one), the platform connects, completes the MCP handshake, and asks the server to enumerate its tools. The discovered tools appear in the Discovered Tools card at the bottom of the server detail page.
If you want to refresh the catalogue (e.g. the server has added new tools since you registered it), use the Rediscover tools button on the server detail page.
The server-level tool list is read-only. To actually grant an agent access to specific tools, you select them inside the agent form's MCP server card — see Agents.
Health checks
The MCP server list page shows a small health badge for each server, based on a recent connectivity probe. You can also trigger a manual check from the server detail page; it tells you whether the platform can reach the server and complete a handshake right now.
Editing and deleting
| Action | Behaviour |
|---|---|
| Edit name | Free-form change, no impact on agents. |
| Edit URL | The server is reconnected and tools are rediscovered. |
| Edit auth type | Credentials are cleared from the form (you must re-enter them) and reapplied on save. |
| Edit credentials | Leave fields blank to keep, paste new values to replace. |
| Disconnect (OAuth) | Tokens are revoked; the server stays in your list but cannot be used until reconnected. |
| Delete | Removes the server entirely. Any agents that reference it will surface a configuration error until the agent is updated. |
Best practices
- Pick Streamable HTTP when the server supports it. SSE is retained only for legacy compatibility; Streamable HTTP is the modern default.
- Use OAuth MCP when available. Per-user tokens give you a much cleaner audit trail than a shared bearer token.
- Restrict tool selection per agent. Even if a server exposes 40 tools, give each agent only the subset it actually needs — see Agents.
- One server, many agents. Register a server once and reuse it across agents. Don't duplicate the row for each agent.
Troubleshooting
| Issue | Resolution |
|---|---|
| Tools list is empty after save | The platform couldn't enumerate tools. Verify URL + transport, hit Rediscover tools, and check whether the server requires authentication. |
| Health check fails | The server is unreachable from the platform. Check DNS, firewall, and that the URL points at the correct MCP endpoint. |
| "Popup blocked" on OAuth connect | Allow popups for the Zynap dashboard domain in your browser, then click Connect again. |
| "Re-authorization required" on a connected server | The provider invalidated the refresh token (typically when consent is revoked or after a long idle period). Click Reconnect. |
| OAuth popup closes with no result | The callback page failed to post back. Open the browser console, retry, and contact support if it persists. |
| Tool calls time out at runtime | Increase Request timeout (ms) if the underlying tool is genuinely slow, but verify the server itself is healthy first. |
Updated: 2026-05-04