Skip to main content
Connect a Model Context Protocol (MCP) server to let your Telnyx AI assistant use external tools during a conversation. Depending on the server, those tools can search documentation, retrieve records, or perform actions in another application. This guide walks through configuring a server, attaching it to an assistant, and checking its connection in the Mission Control Portal. Each step includes a screenshot from the portal.

​
Before you begin

You need: Use a test assistant for your first integration, especially when tools can create, update, or delete records.

​
About the example

The screenshots use Telnyx Docs - MCP Guide Demo, connected to https://developers.telnyx.com/mcp, and an assistant named MCP Documentation Demo. The selected tool, search_telnyx, searches Telnyx documentation. The public documentation MCP endpoint does not require authentication. A dedicated secret named my-assistant-mcp-api-key was created with a nonfunctional demonstration value solely to illustrate secret-reference selection. For this public endpoint, you can leave API Key empty. For an authenticated MCP server, store and select a valid credential from that server’s provider. Do not use a demonstration value for a real authenticated integration.
Connecting a server to an assistant is different from connecting an external AI client to Telnyx’s API tools. For the latter, see Telnyx MCP Server.

​
1. Store your API key as a secret reference

Skip this step if your MCP server does not require an API key. Open Integration Secrets and select Create New Integration Secret. Enter:
  • Identifier: a recognizable name, such as my-assistant-mcp-api-key.
  • Secret Value: the API key supplied by your MCP provider.
Select Save. The identifier is a reference to the stored credential—not the credential itself. Create an Integration Secret with the identifier my-assistant-mcp-api-key; the secret value is hidden. Confirm the identifier appears in the saved secrets list: The saved my-assistant-mcp-api-key reference on the Integration Secrets page.
You cannot retrieve a secret’s value after storing it. Keep the original credential in your approved secret manager. Never put raw keys in assistant instructions, greetings, screenshots, or documentation examples.

​
2. Open MCP Servers

In the portal’s AI Assistants sidebar section, select Tools, then the MCP Servers tab. You can also open MCP Servers directly. Select Create MCP Server. The Tools page under AI Assistants, with the MCP Servers tab and Create MCP Server button. This page manages server configurations. You will attach the configured server to an individual assistant in step 6.

​
3. Configure the server connection

Enter the connection details supplied by your MCP provider: For the documentation example, use HTTP and https://developers.telnyx.com/mcp.
Connecting over VXC: If your MCP server connects to Telnyx through a Virtual Cross Connect (VXC), contact Telnyx Support or your Telnyx sales representative to obtain the IP addresses to use when configuring the MCP server URL.
Create MCP Server form showing the example name, HTTP transport, public documentation endpoint, and optional timeout. If the endpoint URL contains a credential or grants access on its own, store that URL as an Integration Secret. Use + Append integration secret beneath the URL field to reference it. A URL secret belongs in URL; an API-key secret belongs in API Key.

​
4. Select the API-key reference

For an authenticated server, open the API Key selector and search for the identifier created in step 1. Select my-assistant-mcp-api-key, or the identifier you chose. The selector displays the reference name without exposing its stored value. Searching the MCP API Key selector for my-assistant-mcp-api-key. For the public documentation MCP endpoint, authentication is unnecessary and this field may remain empty. The selection shown above illustrates the reference workflow, not a requirement for that endpoint.

​
5. Choose allowed tools and save

Once the server’s tools are listed, review their names and descriptions. Select only the tools this assistant needs. For a first test, prefer a read-only tool. In this example, select search_telnyx. Leave unrelated tools unselected, then select Save. Allowed Tools with only search_telnyx selected and the secret reference shown above it. Confirm your server appears in the MCP Servers list: The saved Telnyx Docs - MCP Guide Demo server entry.
Tool selection limits what you expose to the assistant. It does not replace authorization enforced by the MCP server and the external application.

​
6. Attach the server to an assistant

Open AI Assistants and select your test assistant. In the assistant editor’s section selector, choose Integrations. Integrations selected in the assistant editor's section selector. Scroll to MCP Servers, select Add MCP server, and choose your configured server. Review the server entry and its Allowed tools list. The assistant's MCP Servers section with Add MCP server, the attached documentation server, search_telnyx, and the play, edit, and remove controls. The distinction is important:
  • AI Assistants → Tools → MCP Servers manages the server configuration.
  • An individual assistant → Integrations → MCP Servers attaches that server to the assistant.
Configuring a server at the account level does not automatically attach it to an assistant.

​
7. Explain when to use the tool, then save

Return to the assistant’s Agent section. Update Instructions to describe when the assistant should call the tool, how to use its response, and what to do if the tool fails. For the documentation-search example:
The documentation-search instructions entered in the assistant editor. Use the actual tool names exposed by your server. If a tool changes external data, instruct the assistant to collect the required information and obtain confirmation before taking the action. Enforce access permissions in the external service as well. Select Save at the bottom of the editor. Reopen the assistant and confirm the instructions and attached MCP server remain configured. Save controls at the bottom of the assistant editor.

​
8. Test the MCP connection with the play button

In the assistant’s Integrations → MCP Servers section, click the play button on the server entry. This initiates the MCP connection and discovers its tools without starting an assistant conversation. The MCP entry with the circular play button to the right of the server name and allowed tools. A successful test displays MCP server connected successfully. Review the tools listed on the entry and confirm the intended tool is available. The portal confirmation: MCP server connected successfully. If the connection fails or tools are missing, check the endpoint URL, transport, and credential reference before continuing.
Connection and tool discovery are not the same as executing a tool. A successful play-button test does not prove that the assistant can complete a particular task or that the credential has every permission needed by that task.

​
9. Test the assistant’s use of the tool

Open Test assistant in the assistant editor and choose an appropriate testing option. The captured menu shows Inbound call and Outbound call. For voice testing setup, see the Voice Assistant Quickstart. The Test assistant menu showing Inbound call and Outbound call options. For this example, ask: “Search the Telnyx documentation for how to add an MCP server to an AI assistant.” During validation:
  • Confirm the assistant actually invokes the intended tool; a plausible answer alone is not proof.
  • Review the conversation in Conversation History and inspect MCP-server logs if you operate the server.
  • Compare the answer with the documentation returned by the tool.
  • Check that errors are handled honestly rather than reported as successful actions.
For tools that modify data, use disposable test records and verify the result in the external application.

​
Troubleshooting