> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # Tools > MCP servers and REST APIs on the instance, served to agents as one MCP server. An instance combines the tools of every Model Context Protocol (MCP) server and REST API added to it into one MCP server at `{gateway_url}/mcp`. The agent connects one MCP client to the gateway instead of one to each server. The gateway routes each tool request to the server or API that owns the tool, and authenticates to it with that target's own credentials. It serves the MCP servers' prompts and resources the same way. ## Set Up ### MCP Servers [`POST /v2/agent_gateways/{id}/mcp_servers`](https://developers.telnyx.com/api-reference/agent-gateway-mcp-servers/add-an-mcp-server) adds a server by its MCP endpoint. This one runs inside the user's network, on a [WireGuard peer](https://developers.telnyx.com/docs/agent-gateway/vpc/wireguard-peers/target-as-peer.md) of the instance's [*Network*](https://developers.telnyx.com/docs/network/overview.md), and the gateway sends it an [API key](https://developers.telnyx.com/docs/agent-gateway/outbound/api-keys.md): ```json theme={null} { "name": "orders", "url": "http://172.27.0.3:9000/mcp", "auth": { "type": "api_key", "value": "example-orders-key" } } ``` ### APIs [`POST /v2/agent_gateways/{id}/apis`](https://developers.telnyx.com/api-reference/agent-gateway-apis/add-an-api) adds a REST API by the URL of its OpenAPI description, in JSON. Each operation in the description becomes one tool. When the agent invokes the tool, the gateway sends the operation's HTTP request to the API itself, with no MCP server in between. This public API needs no `auth`: ```json theme={null} { "name": "petstore", "spec_url": "https://petstore3.swagger.io/api/v3/openapi.json", "base_url": "https://petstore3.swagger.io/api/v3" } ``` The gateway reads OpenAPI 3.0, OpenAPI 3.1, and Swagger 2.0. Without a `base_url`, it takes the first entry in the description's `servers`. The gateway reaches an MCP server or API across the instance's *Network*, so either can stay off the internet. ### Outbound Authentication Outbound authentication is not a resource of its own. Each MCP server and API holds its method and the credentials themselves in `auth`, and the gateway authenticates to it with them on every request. Responses return only `auth.type`. `auth.type` picks the method: | `auth.type` | Method | | - | - | | `api_key`, `bearer_token`, `basic`, `token`, `authorization` | [API keys](https://developers.telnyx.com/docs/agent-gateway/outbound/api-keys.md) | | `oauth_client_credentials` | [OAuth client credentials](https://developers.telnyx.com/docs/agent-gateway/outbound/oauth-client-credentials.md) | | `passthrough` | [Token passthrough](https://developers.telnyx.com/docs/agent-gateway/outbound/token-passthrough.md) | | `aws_sigv4` | [AWS Signature Version 4](https://developers.telnyx.com/docs/agent-gateway/outbound/aws-signature-v4.md), for MCP servers only | | `none` | No credential, as when `auth` is left out | OAuth authorization code and OAuth token exchange are Planned. ### Settings Each MCP server and API has: * A `name`, which prefixes its tools. A name holds up to 100 letters, digits, `_`, and `.`, and is unique on the instance, regardless of case, across MCP servers and APIs. * Its address. An MCP server has a `url` and a `transport`, Streamable HTTP (`http`, the default) or Server-Sent Events (`sse`). An API has a `spec_url` and a `base_url`. * An `auth`, its [outbound authentication](#outbound-authentication) method. * `tools`, the tools it exposes to every key, by name. `[]` exposes every tool. * `static_headers`, sent on every request, and `forwarded_headers`, copied from the agent's request by name. * `open_to_every_key`, which opens it to every key on the instance. Otherwise, only the keys [granted](https://developers.telnyx.com/docs/agent-gateway/authorization/tool-permissions.md) it may use it. Only the `name` and the `url` or `spec_url` are required. ### Operations as Tools The gateway makes one tool from each `get`, `post`, `put`, `patch`, and `delete` operation in an API's description: | Tool Part | Taken From | | - | - | | Name | The `operationId`, lowercased, with spaces as underscores, after the API's name and a hyphen. An operation without an `operationId` is named from its method and path. | | Description | The operation's `summary`, or its `description`, or its method and path. | | Arguments | Each path and query parameter, and a JSON request body as one `body` argument with the body's top-level properties. | The operation `findPetsByStatus` on the API `petstore` is the tool `petstore-findpetsbystatus`. Header and cookie parameters are not sent to the API. A request body defined by a `$ref` reaches the agent as an object with no properties. ### Changes [`PATCH /v2/agent_gateways/{id}/mcp_servers/{server_id}`](https://developers.telnyx.com/api-reference/agent-gateway-mcp-servers/update-an-mcp-server) changes a server's settings, and [`PATCH /v2/agent_gateways/{id}/apis/{api_id}`](https://developers.telnyx.com/api-reference/agent-gateway-apis/update-an-api) changes an API's. An update replaces `auth` whole, and `{"type": "none"}` removes the credential. `DELETE` on the same paths removes the server or API. ## Use ### Connections Any MCP client connects to `{gateway_url}/mcp` over [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http), at protocol versions `2024-11-05` through `2025-11-25`. The client presents its [key](https://developers.telnyx.com/docs/agent-gateway/authentication/keys.md) as a bearer token, `Authorization: Bearer `. ### Tool Names Every tool's name starts with its server's or API's name and a hyphen. The tool `get_order` on the server `orders` is `orders-get_order`: ```json Output theme={null} { "tools": [ { "name": "orders-create_ticket", "description": "Open a support ticket with a subject.", ... }, { "name": "orders-get_order", "description": "Look up an order by its ID.", ... } ] } ``` Prompts carry the same prefix, so names stay unique across servers. ### Server Scoping `{gateway_url}/mcp/{server}` serves only that server's tools, still prefixed. A comma-separated list, such as `{gateway_url}/mcp/github,jira`, serves several. The `x-mcp-servers` header narrows `{gateway_url}/mcp` the same way, with a comma-separated list of server names. A path or header narrows what the agent sees. It never adds a server the agent has no [permission](https://developers.telnyx.com/docs/agent-gateway/authorization/tool-permissions.md) to use. ### Results An API tool's result is the API's response body when the response is in the `2xx` range. Any other response is an error result that names the HTTP status, without the API's response body: ```text Output theme={null} Error: upstream returned HTTP 404 ``` ### Tool Search With tool search Preview on for a key, `tools/list` returns four search tools in place of the full catalog. Two of them reach MCP tools: * `mcp_tool_search` takes a `query` and an optional `top_k`, 5 by default. It returns the matching tools, each with its name, description, and input schema. * `mcp_tool_call` takes a `tool_name` and its `arguments`, and invokes that tool. The other two, `agent_search` and `skill_search`, find agents and skills by query. Matching is by keyword. A tool scores a point for each word of the query found in its name or description, and a tool that scores nothing is left out. With an embedding model set on the instance, matching is by meaning instead. Search covers only the tools the key may use, and `mcp_tool_call` applies the same [tool permissions](https://developers.telnyx.com/docs/agent-gateway/authorization/tool-permissions.md) as a direct request.