> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discover MCP Functions

> Connects to an MCP server and returns the functions it offers, so you can pick them for an MCP tool. It works with servers your browser can't reach directly, and resolves secret placeholders without exposing them.



## OpenAPI

````yaml /api-reference/openapi.json post /v2/voice-agents/web-tool/mcp/discover
openapi: 3.0.1
info:
  title: Hamsa API
  description: >-
    The Hamsa API: voice agents and their calls, phone numbers, batch calls and
    knowledge bases; speech to text, text to speech, voices and AI content.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tryhamsa.com
security: []
paths:
  /v2/voice-agents/web-tool/mcp/discover:
    post:
      summary: List the functions of an MCP server
      description: >-
        Connects to an MCP server and returns the functions it offers, so you
        can pick them for an MCP tool. It works with servers your browser can't
        reach directly, and resolves secret placeholders without exposing them.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - serverUrl
              properties:
                serverUrl:
                  type: string
                  format: uri
                  description: MCP server URL (Streamable HTTP or SSE).
                  example: https://mcp.example.com/sse
                authToken:
                  type: string
                  nullable: true
                  description: >-
                    Authorization header value with its prefix, e.g. `Bearer
                    xxx`. May use `{{secrets.NAME}}` placeholders from your
                    project secrets. `null` for none.
                  example: Bearer {{secrets.MCP_TOKEN}}
                httpHeaders:
                  type: object
                  additionalProperties:
                    type: string
                  description: >-
                    Extra headers for the MCP connection. Values may use
                    `{{secrets.NAME}}` placeholders.
                  example:
                    X-Workspace: support
                timeOut:
                  type: number
                  minimum: 1
                  maximum: 60
                  description: Timeout in seconds (1-60). Default 30.
                  example: 10
            examples:
              token:
                summary: With a secret token
                value:
                  serverUrl: https://mcp.example.com/sse
                  authToken: Bearer {{secrets.MCP_TOKEN}}
                  timeOut: 10
              public:
                summary: No auth
                value:
                  serverUrl: https://mcp.example.com/mcp
                  authToken: null
              headers:
                summary: Extra headers
                value:
                  serverUrl: https://mcp.example.com/mcp
                  httpHeaders:
                    X-Api-Key: '{{secrets.MCP_KEY}}'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      functions:
                        type: array
                        items:
                          $ref: '#/components/schemas/McpToolFunction'
        '400':
          description: >-
            Invalid body, an unsafe server URL, a `{{secrets.NAME}}` placeholder
            with no matching secret, or the server can't be reached or is not an
            MCP server. `message` says which; `messageKey` is
            `SomethingWentWrong` for these.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '401':
          description: 'Unauthorized: missing or invalid API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '403':
          description: >-
            A limited key without the `tools:update` scope, or a role that can't
            edit APIs & MCPs (`ScopeNotAllowed`, `params.scope` is
            `tools:update`). Or the request uses `{{secrets.NAME}}` and your API
            key or role can't read secrets (`WebToolSecretsPermissionRequired`;
            needs the `secrets:read` scope). Requests without secret references
            don't need it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Server Side Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    McpToolFunction:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Function name.
          example: create_ticket
        description:
          type: string
          description: What the function does, as the server describes it.
          example: Create a support ticket
        inputSchema:
          type: object
          additionalProperties: true
          description: JSON Schema of the function inputs, as the server reports it.
          example:
            type: object
            properties:
              title:
                type: string
            required:
              - title
    ErrorSchema:
      type: object
      properties:
        code:
          type: integer
          description: >-
            Service error code: the HTTP status with a service prefix (for
            example `8404`). Missing when the service has no code for that
            status.
          example: 8404
        message:
          type: string
          description: >-
            What went wrong. Some services (calls and recordings) put the error
            key here, for example `CallNotFoundOrUnavailable`, and send no
            `messageKey`.
          example: Policy not found!
        messageKey:
          type: string
          description: >-
            Stable key for the error, safe to match on in code. Not returned by
            every service.
          example: PolicyNotFound
        params:
          type: object
          additionalProperties: true
          description: >-
            Details for some errors (for example `reason`). Not returned by
            every service.
          example:
            reason: NO_DRAFT
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Pass the API key in the Authorization header, You need to put Token
        keyword before the API key. e.g. 'Authorization: Token <api-key>'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.