# Custom MCP servers

https://docs.golubvoice.com/en/tools/custom-mcp/

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

1. Select **Add server**.
2. Enter a recognizable **Server name** and the **HTTPS endpoint**.
3. If authentication is required, select **Add header**, enter **Header name** and **Secret header value**, and repeat for any additional supported headers.
4. Select **Discover and save**. This contacts the server and saves the account connection; it does not publish tools for the agent.
5. 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](https://docs.golubvoice.com/en/agents/publishing/) to inspect or restore a saved configuration.

```text
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](https://docs.golubvoice.com/en/tools/connectors/) for completion rules.