Connecting an external MCP server to MCP Hub

Get an IAM token, which is required for authentication.

Save the IAM token to an environment variable:

export IAM_TOKEN="<IAM_token_contents>"

Create a file with the request body, e.g., body.json:

body.json

{
  "folderId": "<folder_ID>",
  "name": "<MCP_server_name>",
  "description": "<MCP_server_description>",
  "serviceAccountId": "<service_account_ID>",
  "public": "true|false",
  "tools": [
    {
      "name": "<tool_name>",
      "description": "<tool_description>",
      "inputJsonSchema": "<tool_JSON_schema>",
      "action": {
        "mcpCall": {
          "url": "<MCP_server_URL>",
          "toolCall": {
            "toolName": "<tool_name>",
            "parametersJson": "<input_parameters>"
          },
          "transport": "<transport_mechanism>",
          "unauthorized": {}
        }
      }
    }
  ]
}

Where:

• folderId: ID of the folder the MCP server is created in. Make sure to assign the serverless.mcpGateways.editor and iam.serviceAccounts.user roles or higher for this folder to your account.

• name: Name of the new MCP server. Follow these naming requirements:

  • It must be from 2 to 63 characters long.
  • It can only contain lowercase Latin letters, numbers, and hyphens.
  • It must start with a letter and cannot end with a hyphen.

• description: Description of the new MCP server.

• serviceAccountId: ID of the service account your MCP server will use to access Yandex Cloud services and resources. The service account should get the roles sufficient to access these resources and services.

• public: Type of the new server. The possible values are:

  • true: To create a public MCP server.
  • false: To create a private MCP server.

• tools: Description of the tools you add to the MCP server:

  • name: Tool name. Follow these naming requirements:

    • It must be from 2 to 63 characters long.
    • It can only contain lowercase Latin letters, numbers, and hyphens.
    • It must start with a letter and cannot end with a hyphen.

  • description: Tool description.

  • inputJsonSchema: JSON schema describing the tool's input parameters.

    JSON schema:

    {
      properties?: { [key: string]: object };
      required?: string[];
      type: "object";
    }
    

    JSON struture example

    {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City name or zip code"
        }
      },
      "required": ["location"]
    }
    

  • action.httpCall: Description of configuration parameters for connection to an external MCP server:

    • url: External MCP server URL, e.g., https://mcp.example.com.

    • toolName: Tool name. Follow these naming requirements:

      • It must be from 2 to 63 characters long.
      • It can only contain lowercase Latin letters, numbers, and hyphens.
      • It must start with a letter and cannot end with a hyphen.

    • parametersJson: Parameters fed into the tool, in jq template format.

    • transport: Transport mechanism type for interacting with the MCP server. Available types:

      • STREAMABLE: State-of-the-art transport mechanism. Your AI agent will be able to get updates (events) from the server without a persistent HTTP connection.
      • SSE: Legacy transport mechanism. Your AI agent will be able to get updates from the server over the same persistent HTTP connection.

    • "unauthorized": {}: Provide this value if the external MCP server does not require authentication. If authentication is required, provide either the authorization header or serviceAccount field in the request body instead of unauthorized. For more information, see McpGateway.Create in the API reference.

  Request body example

  {
    "folderId": "b1gt6g8ht345********",
    "name": "my-external-mcp-server",
    "description": "my sample external MCP-server",
    "serviceAccountId": "ajegtlf2q28a********",
    "public": "true",
    "tools": [
      {
        "name": "tool-name",
        "description": "tool description",
        "inputJsonSchema": "{\"type\":\"object\",\"properties\":{\"location\":{\"type\":\"string\",\"description\":\"City name or zip code\"}},\"required\":[\"location\"]}",
        "action": {
          "mcpCall": {
            "url": "https://mcp.example.com",
            "toolCall": {
              "toolName": "tool-name",
              "parametersJson": "//( . )"
            },
            "transport": "SSE",
            "unauthorized": {}
          }
        }
      }
    ]
  }
  

Use the McpGateway.Create REST API method to create a new MCP server in the folder:

curl \
  --request POST \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --data "@body.json" \
  "https://serverless-mcp-gateway.api.cloud.yandex.net/mcpgateway/v1/mcpGateways"

Result:

{
  "done": false,
  "metadata": {
    "@type": "type.googleapis.com/yandex.cloud.serverless.mcpgateway.v1.CreateMcpGatewayMetadata",
    "mcpGatewayId": "db815a8nma7u********",
    "folderId": "b1gt6g8ht345********"
  },
  "id": "db8o404e7f2v********",
  "description": "Create MCP Gateway",
  "createdAt": "2025-12-22T18:04:42.776181560Z",
  "createdBy": "ajeol2afu1js********",
  "modifiedAt": "2025-12-22T18:04:42.776181560Z"
}

Save the new MCP server's ID (the mcpGatewayId field value) for the next step.

Wait until the MCP server is created, then view its details by specifying the ID you saved in the previous step.

curl \
  --request GET \
  --header "Authorization: Bearer $IAM_TOKEN" \
  "https://serverless-mcp-gateway.api.cloud.yandex.net/mcpgateway/v1/mcpGateways/<MCP_server_ID>"

{
  "tools": [
    {
      "action": {
        "mcpCall": {
          "toolCall": {
            "toolName": "tool-name",
            "parametersJson": "//( . )"
          },
          "unauthorized": {},
          "url": "https://mcp.example.com",
          "transport": "SSE"
        }
      },
      "name": "tool-name",
      "description": "tool description",
      "inputJsonSchema": "{\"type\":\"object\",\"properties\":{\"location\":{\"type\":\"string\",\"description\":\"City name or zip code\"}},\"required\":[\"location\"]}"
    }
  ],
  "logOptions": {
    "disabled": false
  },
  "public": true,
  "id": "db815a8nma7u********",
  "folderId": "b1gt6g8ht345********",
  "createdAt": "2025-12-22T18:04:42.819804Z",
  "name": "my-external-mcp-server",
  "description": "my sample external MCP-server",
  "status": "ACTIVE",
  "baseDomain": "https://db815a8nma7u********.99igvxy3.mcpgw.serverless.yandexcloud.net",
  "serviceAccountId": "ajegtlf2q28a********",
  "cloudId": "b1gia87mbaom********"
}