Telnyx MCP Servers API

openapi: 3.2.0
info:
  title: Telnyx MCP Servers API
  version: 2.0.0
  contact:
    email: support@telnyx.com
  x-endpoint-cost: light
  x-refined-note:
  - x-latency-category differs across the merged source definitions and was not carried
  description: 'Operations tagged MCP Servers across 3 of this provider''s published API definitions: telnyx-openapi.json, telnyx-openapi.yml, telnyx-openapi_2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: MCP Servers
paths:
  /ai/mcp_servers:
    get:
      tags:
      - MCP Servers
      summary: List MCP Servers
      description: Returns a paginated list of the MCP servers configured on your account, with optional filtering by type or URL.
      operationId: list_mcp_servers
      parameters:
      - name: type
        in: query
        description: Filter results by type.
        required: false
        schema:
          type: string
          title: Type
      - name: url
        in: query
        description: Filter results by url.
        required: false
        schema:
          type: string
          title: Url
      - name: page[size]
        in: query
        description: Number of items to return per page.
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Page[Size]
      - name: page[number]
        in: query
        description: Page number to retrieve (1-based).
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page[Number]
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPServersListResponse'
              example:
              - id: Id
                name: Name
                type: Type
                url: Url
                created_at: '2024-01-23T18:10:02.574Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - MCP Servers
      summary: Create MCP Server
      description: Creates a new MCP server configuration on your account and returns the created server.
      operationId: create_mcp_server
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMCPServerRequest'
            example:
              name: Name
              type: Type
              url: Url
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPServer'
              example:
                id: Id
                name: Name
                type: Type
                url: Url
                created_at: '2024-01-23T18:10:02.574Z'
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
        '400':
          description: Bad Request / Validation Failed (10015). Invalid, duplicate, empty, malformed, or overlong Idempotency-Key headers are rejected by Edge with HTTP 400 and error code 10015.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inference-embedding_ErrorResponse'
        '409':
          $ref: '#/components/responses/IdempotencyConflictResponse'
        '413':
          description: Payload Too Large. A request sent with an Idempotency-Key whose body exceeds the endpoint's Edge replay-protection limit (256 KB) is rejected before it reaches the service. Requests sent without the header are not subject to this limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inference-embedding_ErrorResponse'
        '422':
          description: Validation Error. Reusing an Idempotency-Key with a different request body also returns 422 with error code 10027.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/HTTPValidationError'
                - $ref: '#/components/schemas/inference-embedding_ErrorResponse'
        '503':
          description: Service unavailable (10016), including unavailable Edge idempotency protection for a keyed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inference-embedding_ErrorResponse'
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /ai/mcp_servers/{mcp_server_id}:
    delete:
      tags:
      - MCP Servers
      summary: Delete MCP Server
      description: Permanently deletes the specified MCP server configuration from your account.
      operationId: delete_mcp_server
      parameters:
      - name: mcp_server_id
        in: path
        description: Unique identifier of the mcp server.
        required: true
        schema:
          type: string
          title: Mcp Server Id
      responses:
        '200':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
              example:
                detail:
                - loc:
                  - string
                  msg: Message
                  type: Error Type
    get:
      tags:
      - MCP Servers
      summary: Get MCP Server
      description: Retrieve details for a specific MCP server.
      operationId: get_mcp_server
      parameters:
      - name: mcp_server_id
        in: path
        description: Unique identifier of the mcp server.
        required: true
        schema:
          type: string
          title: Mcp Server Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPServer'
              example:
                id: Id
                name: Name
                type: Type
                url: Url
                created_at: '2024-01-23T18:10:02.574Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - MCP Servers
      summary: Update MCP Server
      description: Updates the specified MCP server's configuration and returns the updated server.
      operationId: update_mcp_server
      parameters:
      - name: mcp_server_id
        in: path
        description: Unique identifier of the mcp server.
        required: true
        schema:
          type: string
          title: Mcp Server Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMCPServerRequest'
            example:
              id: Id
              name: Name
              type: Type
              url: Url
              created_at: '2024-01-23T18:10:02.574Z'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPServer'
              example:
                id: Id
                name: Name
                type: Type
                url: Url
                created_at: '2024-01-23T18:10:02.574Z'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
components:
  headers:
    IdempotentReplayed:
      description: Present with value `true` when Edge replayed a stored successful response for the supplied Idempotency-Key. Omitted for first-time requests and error responses.
      schema:
        type: boolean
        enum:
        - true
        example: true
  schemas:
    email_ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
        suppressed:
          type: array
          description: Present when every recipient is suppressed, so the request is rejected and no message is created.
          items:
            $ref: '#/components/schemas/SuppressedRecipient'
      required:
      - errors
    inference-embedding_ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/inference-embedding_ErrorObject'
      required:
      - errors
    UpdateMCPServerRequest:
      type: object
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        type:
          type: string
          title: Type
        url:
          type: string
          title: Url
        api_key_ref:
          type:
          - string
          - 'null'
          title: Api Key Ref
        allowed_tools:
          type:
          - array
          - 'null'
          items:
            type: string
          title: Allowed Tools
        created_at:
          type: string
          format: date-time
          title: Created At
      title: UpdateMCPServerRequest
    SuppressedRecipient:
      type: object
      properties:
        to:
          type: string
          format: email
          description: Suppressed recipient email address.
        reason:
          type: string
          description: Suppression reason returned by the recipient suppression service.
        scope:
          type: string
          description: Scope at which the suppression applies.
        override_allowed:
          type: boolean
          description: Whether an authorized send may override this suppression.
      required:
      - to
      - reason
      - scope
      - override_allowed
    MCPServersListResponse:
      type: array
      items:
        $ref: '#/components/schemas/MCPServer'
      title: MCPServersListResponse
    ErrorObject:
      type: object
      properties:
        code:
          type: string
          description: Telnyx error code. Send admission errors include account daily quota 10011 and sender-domain ramp code domain_graduation_limit_exceeded. Edge idempotency errors use 10027 or 10036. Fallback 404/500 responses from the framework may use string status codes ('404', '500') instead.
          enum:
          - '10001'
          - '10006'
          - '10007'
          - '10011'
          - '10015'
          - '10016'
          - '10019'
          - domain_graduation_limit_exceeded
          - recipient_suppressed
          - reputation_suspended
          - '404'
          - '500'
          - '10027'
          - '10036'
        title:
          type: string
        detail:
          description: Human-readable error detail. Changeset responses may return a structured object.
          oneOf:
          - type: string
          - type: object
            additionalProperties: true
        source:
          type: object
          additionalProperties: true
          nullable: true
        meta:
          type: object
          additionalProperties: true
          nullable: true
          description: Additional metadata. Present on 401 errors with a documentation URL.
      required:
      - code
      - title
      - detail
    CreateMCPServerRequest:
      type: object
      properties:
        name:
          type: string
          title: Name
        type:
          type: string
          title: Type
        url:
          type: string
          title: Url
        api_key_ref:
          type:
          - string
          - 'null'
          title: Api Key Ref
        allowed_tools:
          type:
          - array
          - 'null'
          items:
            type: string
          title: Allowed Tools
      required:
      - name
      - type
      - url
      title: CreateMCPServerRequest
    MCPServer:
      type: object
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        type:
          type: string
          title: Type
        url:
          type: string
          title: Url
        api_key_ref:
          type:
          - string
          - 'null'
          title: Api Key Ref
        allowed_tools:
          type:
          - array
          - 'null'
          items:
            type: string
          title: Allowed Tools
        created_at:
          type: string
          format: date-time
          title: Created At
      required:
      - id
      - name
      - type
      - url
      - created_at
      title: MCPServer
    inference-embedding_ErrorObject:
      type: object
      properties:
        code:
          type: string
          description: Telnyx error code. Edge idempotency errors use 10015, 10027, or 10036; idempotency protection outages use 10016; replay-cap 413s surface 10007. Fallback 404/500 responses from the framework may use string status codes ('404', '500') instead.
          enum:
          - '10007'
          - '10015'
          - '10016'
          - '10027'
          - '10036'
          - '404'
          - '500'
        title:
          type: string
        detail:
          type: string
        source:
          type: object
          properties:
            pointer:
              type: string
      required:
      - code
      - title
    ValidationError:
      title: ValidationError
      required:
      - loc
      - msg
      - type
      type: object
      properties:
        loc:
          title: Location
          type: array
          items:
            anyOf:
            - type: string
            - type: integer
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
      example:
        detail:
        - loc:
          - body
          - name
          msg: Field required
          type: missing
    HTTPValidationError_2:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
  responses:
    IdempotencyConflictResponse:
      description: A request with the same Idempotency-Key is still being processed (10036). Retry later with the same key and request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/email_ErrorResponse'
          example:
            errors:
            - code: '10036'
              title: Resource is being processed
              detail: A request with this Idempotency-Key is already being processed.
              source:
                pointer: /header/Idempotency-Key
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Optional opaque, unquoted key for safely retrying the same logical request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores. Generate a unique UUID v4 for each operation and reuse it only when retrying that operation with the same request. Invalid headers—including duplicate, empty, malformed, or overlong values—return 400 with error code 10015. A request already in progress with the same key returns 409; reusing the key with a different request returns 422. Only successful responses are replayed, for up to 24 hours. Do not include sensitive data in the key.
      schema:
        type: string
        minLength: 1
        maxLength: 255
        pattern: ^[A-Za-z0-9_-]{1,255}$
      example: 8e03978e-40d5-43e8-bc93-6894a57f9326
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    pay-connectors_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key, not the processor bearer token.
    telnyxApiKey:
      type: http
      scheme: bearer
      description: Management-only Telnyx account credential.
x-refined-from:
- telnyx-openapi.json
- telnyx-openapi.yml
- telnyx-openapi_2.json
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt