Add an MCP server
Adds an MCP server. The instance serves its tools at {gateway_url}/mcp, each named with the server’s name and a hyphen, to the keys granted the server and, with open_to_every_key, to every key. The instance must be ready; otherwise the request answers 409.
POST
/
agent_gateways
/
{instance_id}
/
mcp_servers
JavaScript
import Telnyx from 'telnyx';
const client = new Telnyx({
apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
const AgentGatewayMcpServer = await client.agentGateways.mcpServers.create('instance_id', {
name: 'name',
url: 'url',
});
console.log(AgentGatewayMcpServer.data);import os
from telnyx import Telnyx
client = Telnyx(
api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted
)
agent_gateway_mcp_server = client.agent_gateways.mcp_servers.create(
instance_id="instance_id",
name="name",
url="url",
)
print(agent_gateway_mcp_server.data)
package main
import (
"context"
"fmt"
"github.com/team-telnyx/telnyx-go"
"github.com/team-telnyx/telnyx-go/option"
)
func main() {
client := telnyx.NewClient(
option.WithAPIKey("My API Key"),
)
mCPServer, err := client.AgentGateways.MCPServers.New(
context.TODO(),
"instance_id",
telnyx.AgentGatewayMCPServerNewParams{
Name: "name",
URL: "url",
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", mCPServer.Data)
}
package com.telnyx.sdk.example;
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.agentGateways.mcpServers.McpServerCreateParams;
public final class Main {
private Main() {}
public static void main(String[] args) {
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
McpServerCreateParams params = McpServerCreateParams.builder()
.name("name")
.url("url")
.build();
var response = client.agentGateways().mcpServers().create("instance_id", params);
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
agent_gateway_mcp_server = telnyx.agent_gateways.mcp_servers.create("instance_id", name: "name", url: "url")
puts(agent_gateway_mcp_server)<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';
use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;
$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');
try {
$agent_gateway_mcp_server = $client->agentGateways->mcpServers->create(
'instance_id',
name: 'name',
url: 'url',
);
var_dump($agent_gateway_mcp_server);
} catch (APIException $e) {
echo $e->getMessage();
}telnyx agent-gateways:mcp-servers create \
--api-key 'My API Key' \
--instance-id 32ce035d-3165-4031-b1a7-a7c0c259590a \
--name name \
--url urlcurl --request POST \
--url https://api.telnyx.com/v2/agent_gateways/{instance_id}/mcp_servers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "orders",
"url": "http://10.40.3.7:9000/mcp",
"auth": {
"type": "api_key",
"value": "example-orders-key"
},
"static_headers": {
"X-Env": "prod"
},
"forwarded_headers": [
"X-Request-Id"
]
}
'{
"data": {
"id": "88d5a97b-4080-4855-8bac-a39811b1dc24",
"name": "orders",
"url": "http://10.40.3.7:9000/mcp",
"transport": "http",
"auth": {
"type": "api_key"
},
"tools": [],
"static_headers": {
"X-Env": "prod"
},
"forwarded_headers": [
"X-Request-Id"
],
"open_to_every_key": false,
"created_at": "2026-10-28T16:50:43.184000Z",
"updated_at": "2026-10-28T16:50:43.184000Z"
}
}{
"errors": [
{
"code": "10012",
"title": "Duplicate resource",
"detail": "Resource is a duplicate.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10012"
},
"source": {
"pointer": "/name"
}
}
]
}{
"errors": [
{
"code": "10009",
"title": "Authentication failed",
"detail": "The required authentication headers were either invalid or not included in the request.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10009"
}
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "The requested resource or URL could not be found.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10005"
}
}
]
}{
"errors": [
{
"code": "99901",
"title": "Instance not ready",
"detail": "The instance is not ready; its engine is not running."
}
]
}{
"errors": [
{
"code": "10027",
"title": "Unprocessable Entity",
"detail": "String should match pattern '^[A-Za-z0-9_.]{1,100}$'",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10027"
},
"source": {
"pointer": "/name"
}
}
]
}{
"errors": [
{
"code": "99903",
"title": "Engine unavailable",
"detail": "The instance's engine did not answer; try again shortly."
}
]
}Authorizations
Telnyx API key
Path Parameters
The Agent Gateway's id.
Body
application/json
A name for the server, unique on the instance across MCP servers and APIs, regardless of case. Up to 100 letters, digits, _, and .. The gateway prefixes the server's tools with it and a hyphen.
Pattern:
^[A-Za-z0-9_.]{1,100}$The server's MCP endpoint, http or https.
http for Streamable HTTP, or sse for Server-Sent Events.
Available options:
http, sse How the gateway authenticates to the server. Replaced whole on an update; {"type": "none"} removes the credential.
- No authentication
- API key
- OAuth client credentials
- Token passthrough
- AWS Signature Version 4
Show child attributes
Show child attributes
The tools the server exposes to every key, by name. [] exposes every tool.
Headers sent on every request.
Show child attributes
Show child attributes
Headers copied from the agent's request, by name.
Maximum array length:
32true lets every key on the instance use the server, granted or not.
Response
The added MCP server
Show child attributes
Show child attributes
Was this page helpful?
JavaScript
import Telnyx from 'telnyx';
const client = new Telnyx({
apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
const AgentGatewayMcpServer = await client.agentGateways.mcpServers.create('instance_id', {
name: 'name',
url: 'url',
});
console.log(AgentGatewayMcpServer.data);import os
from telnyx import Telnyx
client = Telnyx(
api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted
)
agent_gateway_mcp_server = client.agent_gateways.mcp_servers.create(
instance_id="instance_id",
name="name",
url="url",
)
print(agent_gateway_mcp_server.data)
package main
import (
"context"
"fmt"
"github.com/team-telnyx/telnyx-go"
"github.com/team-telnyx/telnyx-go/option"
)
func main() {
client := telnyx.NewClient(
option.WithAPIKey("My API Key"),
)
mCPServer, err := client.AgentGateways.MCPServers.New(
context.TODO(),
"instance_id",
telnyx.AgentGatewayMCPServerNewParams{
Name: "name",
URL: "url",
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", mCPServer.Data)
}
package com.telnyx.sdk.example;
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.agentGateways.mcpServers.McpServerCreateParams;
public final class Main {
private Main() {}
public static void main(String[] args) {
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
McpServerCreateParams params = McpServerCreateParams.builder()
.name("name")
.url("url")
.build();
var response = client.agentGateways().mcpServers().create("instance_id", params);
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
agent_gateway_mcp_server = telnyx.agent_gateways.mcp_servers.create("instance_id", name: "name", url: "url")
puts(agent_gateway_mcp_server)<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';
use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;
$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');
try {
$agent_gateway_mcp_server = $client->agentGateways->mcpServers->create(
'instance_id',
name: 'name',
url: 'url',
);
var_dump($agent_gateway_mcp_server);
} catch (APIException $e) {
echo $e->getMessage();
}telnyx agent-gateways:mcp-servers create \
--api-key 'My API Key' \
--instance-id 32ce035d-3165-4031-b1a7-a7c0c259590a \
--name name \
--url urlcurl --request POST \
--url https://api.telnyx.com/v2/agent_gateways/{instance_id}/mcp_servers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "orders",
"url": "http://10.40.3.7:9000/mcp",
"auth": {
"type": "api_key",
"value": "example-orders-key"
},
"static_headers": {
"X-Env": "prod"
},
"forwarded_headers": [
"X-Request-Id"
]
}
'{
"data": {
"id": "88d5a97b-4080-4855-8bac-a39811b1dc24",
"name": "orders",
"url": "http://10.40.3.7:9000/mcp",
"transport": "http",
"auth": {
"type": "api_key"
},
"tools": [],
"static_headers": {
"X-Env": "prod"
},
"forwarded_headers": [
"X-Request-Id"
],
"open_to_every_key": false,
"created_at": "2026-10-28T16:50:43.184000Z",
"updated_at": "2026-10-28T16:50:43.184000Z"
}
}{
"errors": [
{
"code": "10012",
"title": "Duplicate resource",
"detail": "Resource is a duplicate.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10012"
},
"source": {
"pointer": "/name"
}
}
]
}{
"errors": [
{
"code": "10009",
"title": "Authentication failed",
"detail": "The required authentication headers were either invalid or not included in the request.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10009"
}
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "The requested resource or URL could not be found.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10005"
}
}
]
}{
"errors": [
{
"code": "99901",
"title": "Instance not ready",
"detail": "The instance is not ready; its engine is not running."
}
]
}{
"errors": [
{
"code": "10027",
"title": "Unprocessable Entity",
"detail": "String should match pattern '^[A-Za-z0-9_.]{1,100}$'",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10027"
},
"source": {
"pointer": "/name"
}
}
]
}{
"errors": [
{
"code": "99903",
"title": "Engine unavailable",
"detail": "The instance's engine did not answer; try again shortly."
}
]
}