Creating MCP server in code view

Edit online

Define and configure MCP server resources in IBM API Studio by editing YAML files in code view.

You can use code view to:
  • Review resources generated from form view.
  • Create or modify MCP server and tool definitions manually.

When you generate an MCP server from an existing API in the form view, IBM API Studio automatically generates the MCP server, MCP tools, policy, and quota KIND files to process and manage MCP requests.

Table 1. MCP resources
kind Description
MCP core resources
kind: MCPServer Defines the MCP server and acts as the entry point for all requests.
kind: MCPTools Defines the tools that AI agents can invoke through the MCP server.
Policy resources
kind: FreeFlowPolicySequence Defines the main request processing flow in the Build assembly.
kind: Invoke Routes requests from the MCP server to the backend service.
kind: Telemetry Captures monitoring and analytics data.
kind: Throw Handles error responses.
Quota resources
kind: Quota Defines rate limiting for the MCP server.
Open API resources
OpenAPI specification Defines the backend API contract used by the MCP server.

When you register an external MCP server from a third-party service in the form view, IBM API Studio automatically generates the external MCP server, MCP tools, policy, and quota KIND files to process and manage MCP requests.

The generated resources for the external MCP server are as follows:
Table 2. External MCP resources
kind Description
MCP core resources
kind: MCPServer Defines the MCP server and acts as the entry point for all requests.
kind: MCPTools Defines the tools that AI agents can invoke through the MCP server.
Policy resources
kind: FreeFlowPolicySequence Defines the main request processing flow in the Build assembly.
kind: MCPInvoke Routes requests from the external MCP server to the backend service.
kind: Telemetry Captures monitoring and analytics data.
Quota resources
kind: Quota Defines rate limiting for the MCP server.
Open API resources
OpenAPI specification Defines the backend API contract used by the MCP server.

Create or modify an MCP server kind file

The kind field specifies the type of asset that is defined. When you set the kind field to MCPServer, it indicates that the file represents an MCP server configuration. An MCP server defines how one or more MCP tools are exposed to AI agents. It includes server metadata, supported protocol version, hosted tools, and applied policies.

To check the generated MCP server specifications in the Code view,
  1. In IBM API Studio, go to the Explorer.
  2. Expand MCP servers and select the generated MCP server.
  3. Switch to the Code view.
  4. In the project files, open the API_server.yaml file.
MCP server (generated from a Rest API) Kind file

kind: MCPServer
apiVersion: api.ibm.com/v1
metadata:
  name: weather-api-server
  namespace: DPNano_Product_MCPServer
  version: "1.0"
  tags: []
spec:
  title: Weather API MCP Server
  protocolVersion: V2025_11_25
  quota:
    $ref: DPNano_Product_MCPServer:weather-api-quota:1.0
  policy-sequence:
    - $ref: DPNano_Product_MCPServer:weather-api-seq:1.0
  capabilities:
    tools:
      - $ref: DPNano_Product_MCPServer:weather-api-tool:1.0
External MCP server Kind file example

kind: MCPServer
apiVersion: api.ibm.com/v1
metadata:
  name: mcp2-server-aco5z
  namespace: mcp2
  version: 1.0.0
  tags: []
  labels:
    origin: mcp-mcp
spec:
  title: mcp2
  protocolVersion: V2025_11_25
  quota:
    $ref: mcp2:quota-aco5z:1.0.0
  policy-sequence:
    - $ref: mcp2:policy-sequence-aco5z:1.0.0
  capabilities:
    tools:
      - $ref: mcp2:mcp2-tool-aco5z:1.0.0
Table 3. MCP server field descriptions
Category Field Description
  kind Defines the type of asset. The value MCPServer indicates that the file represents an MCP server configuration.
metadata.

Identifies and organizes the MCP server with essential tags and identifiers.

 name Identifies the MCP Server. The name must be unique within the namespace.
namespace Identifies the project.
version Specifies the MCP server version for tracking changes.
tags Assigns keywords to the MCP server for categorizing and filtering MCP servers.
labels origin: mcp-mcp identifies the external MCP server.
spec.

Defines the structure and behavior of the MCPServer.

title MCP server name visible to users and AI agents when browsing MCP assets.
description Describes the purpose and capabilities of the MCP server.
protocolVersion Specifies the supported MCP version.
tools

Lists the MCP tools that are hosted by the MCP server.

Each tool is referenced by using the $ref parameter in the format namespace:mcp_tool_name:version.
policy-sequence Lists the policies applied to the MCP server and enforces them in the defined order. Each policy is referenced by using the $ref parameter in the format namespace:policy_name:version.

Create or modify an MCP tool kind file

The kind field specifies the type of asset that is defined. When you set the kind field to MCPTools, it indicates that the file represents an MCP tool configuration. An MCP tool represents a single action that an AI agent can perform.

To check MCP tool specification in the Code view,
  1. In IBM API Studio, go to the Explorer.
  2. Expand MCP servers and select the generated MCP server.
  3. Switch to Code view.
  4. In the project files, open the API_tool.yaml file.
MCP tool configuration example

kind: MCPTools
apiVersion: api.ibm.com/v1
metadata:
  name: weather-api-tool
  namespace: DPNano_Product_MCPServer
  version: "1.0"
  tags: []
  description: "Tools for accessing Singapore Weather API"
spec:
  tools:
    - name: list-weather-stations
      description: Make a GET request to /weather-stations
      inputSchema:
        type: object
        properties: {}
      title: List Weather Stations
      x-api-binding:
        operationPath: /weather-stations
        operationMethod: GET
        api:
          $path: ./weather-api-spec.json
    - name: get-air-temperature
      description: Make a GET request to /air-temperature
      inputSchema:
        type: object
        properties:
          station_id:
            type: string
            description: The station identifier to filter by a specific station (optional)
            example: S101
          start_time:
            type: string
            description: ISO-8601 timestamp to filter readings from this time (optional)
            example: "2025-11-11T00:00:00+08:00"
          end_time:
            type: string
            description: ISO-8601 timestamp to filter readings up to this time (optional)
            example: "2025-11-11T12:00:00+08:00"
      title: Get Air Temperature
      x-api-binding:
        operationPath: /air-temperature
        operationMethod: GET
        api:
          $path: ./weather-api-spec.json
Table 4. MCP tool field descriptions
Category Field Description
  kind Defines the type of asset. The value MCPTools indicates that the file represents an MCP tool configuration.
metadata.

Identifies and organizes MCP tools with essential tags and identifiers.

 name Identifies the MCP tool. The name must be unique within the namespace.
namespace Identifies the project.
version Specifies the MCP tool version for tracking changes.
tags Assigns keywords to the MCP tool for categorizing and filtering MCP tools.
spec.

Defines the structure and behavior of the MCPTools.

name Identifies the MCP tool operation name used internally by AI agents.
description Describes what the tool does and how it should be used.
inputSchema Defines the input parameters that the tool accepts.
outputSchema (Optional) Defines the expected output structure returned by the tool.
api.$path
Links the MCP tool to the backend OpenAPI definition.
api:
 $path: ./weather-api-spec.json
The referenced OpenAPI document defines the backend operations. The DataPower® Nano Gateway uses this information to route requests to the backend service.