Custom MCP connects an agent to tools offered by a remote service you control or are authorized to use. Connecting a server, selecting tools and publishing the agent are separate steps. Start with a read-only lookup before enabling an action that changes a business record.
Check the server and your access
Use an account administrator session and a Live agent. Open Agents → your agent → Configuration → Custom MCP servers.
The supported transport is Streamable HTTP over public HTTPS on port 443. Use the service’s MCP endpoint, not its ordinary website or REST API address. Local/private-network servers, OAuth sign-in and other transports are not supported. The endpoint must have no query string, fragment or embedded credentials.
Authentication can be omitted for a service that needs none, or supplied through static HTTP headers using Add header. Obtain the header names and values from the service operator. Keep credentials in Secret header value, never in instructions, knowledge files, the endpoint or a support example.
Connect and discover
- Select Add server.
- Enter a recognizable Server name and the HTTPS endpoint.
- If authentication is required, select Add header, enter Header name and Secret header value, and repeat for any additional supported headers.
- Select Discover and save. This contacts the server and saves the account connection; it does not publish tools for the agent.
- Read the result. Success says Server discovered. Select tools for this agent, then Save and Publish. The server card lists its tools. An empty catalog says This server has no tools.
For a fictional setup, use the name Workshop orders and an endpoint such as https://mcp.example.com/orders. This is an illustration, not a working server. Use your own supported endpoint and operator-provided authentication; no example secret is needed.
Select tools and publish
Under Tools available to this agent, check only the tools needed for the job. New tools are not selected automatically. Tools marked Unsupported schema cannot be selected. You may select at most 16 tools in total across the agent’s servers.
For example, a fictional server offers lookup_order, set_order_note and clear_order_note. Select only lookup_order for an agent that should answer order-status questions. Enable a write tool only when you have defined who may request it and what confirms completion. Identical tool names on different servers are separate choices; review the server card as well as the name.
Select Save draft, review the saved selection, then select Publish when ready. Discovery alone and checked boxes alone do not change the published agent. Use Saving, publishing and version history to inspect or restore a saved configuration.
Use the selected order lookup only after obtaining the caller's reference.
Explain the returned status briefly. Do not invent a missing order.
If a tool fails, say that the result could not be confirmed.
Do not claim that a note was saved unless the business system confirms it.
If a write result is uncertain, check the record before repeating the action.
Handle discovery failures
| Console result | What to check |
|---|---|
| The server rejected the headers | Ask the service operator to verify the credentials and required header names. |
| The server address is blocked / invalid endpoint | Use a public HTTPS MCP endpoint on port 443 without a query or fragment. |
| The server did not respond in time | Check the endpoint and service availability before another discovery attempt. |
| Unsupported MCP catalog / catalog too large | Ask the operator to provide a compatible, bounded tool catalog. An ordinary API response is not an MCP catalog. |
| The change could not be confirmed | Use Retry this change to check that same change before starting another. |
If the server list cannot load, use Reload servers. Do not treat a failed discovery as a connected service or select a similarly named tool from another server as a substitute.
Update credentials or tools
Edit server lets you change the name or endpoint. Saved header values are hidden. Leave Replace saved headers off to preserve them; enable it only when supplying the complete replacement header set.
Discover again checks the current catalog. A newer catalog does not silently replace the agent’s pinned selection. If the console reports a newer tool version, choose Use this tool version, inspect the retained choices, then Save draft and Publish. Removed or unsupported tools may drop from the selection.
Disconnect is an account-level change that can affect other published agents. Read its affected-agent and active-call warning. Future submissions stop; already submitted work may finish. Remove the disconnected selection from affected agents and publish their corrected configuration before reconnecting.
Interpret tool results honestly
A server response is information from that server, not independent proof that a booking, message or other business change occurred. Failed, Result uncertain, Cancelled and Not submitted are different outcomes. Inspect the underlying record before retrying an uncertain write; a duplicate may create another external effect. See Tools and connectors for completion rules.