Management AI MCP

Use this tool to interact with the various AI functionalities in IBM® API Connect.

The Management AI MCP tool provides capabilities for generating and modifying gateway policies and creating spectral rules from natural language descriptions.
Limitations
The following are the limitations of this tool:
  • This tool relies on foundation models to generate spectral rules from natural language descriptions.
  • Like all AI models, the output can include errors or hallucinations.
  • Validation of the generated spectral rule is essential to ensure accuracy.
  • Use Spectral rule validator to confirm that the generated rule is valid and functions as intended.
The Management AI MCP tool supports the following operations:

ListGatewayPolicies

Use this operation to list the policies available for policy generation. These policies are used in DataPower API gateway and DataPower nano gateway.

The following table describes the policy names and gateway types for the DataPower API gateway policies available for generation.

Table 1. Policy types and descriptions
Policy name Gateway type Description
activity-log dataPower-api-gateway Configures logging preferences for API activity that is stored in IBM API Connect analytics.
client-security dataPower-api-gateway Extends client authentication access for your APIs.
extract dataPower-api-gateway Extracts and transforms data from fields in the API context.
gatewayscript dataPower-api-gateway Runs a specified DataPower GatewayScript program.

For more information about policies, see Built-in policies.

The following table describes the policy names and gateway types for the DataPower nano gateway policies available for generation.
Table 2. Policy types and descriptions
Policy name Gateway type Description
block datapower-nano-gateway Block requests based on specific criteria, such as IP address
cors datapower-nano-gateway Configures Cross-Origin Resource Sharing (CORS) settings for your API.
invoke datapower-nano-gateway Calls another service from in the assembly of your API.
parse datapower-nano-gateway Controls the parsing of an incoming document in your API.
ratelimit datapower-nano-gateway Controls the rate of requests to your API.
redact datapower-nano-gateway Masks sensitive information from API requests and responses.
remove datapower-nano-gateway Deletes specific headers or parameters from API requests or responses.
set datapower-nano-gateway Sets adds, or combines values of a runtime variable.
validate datapower-nano-gateway Ensures that incoming API requests are valid to their specifications

For more information about policies, see DataPower Nano Gateway API assembly policies.

Example prompts

  • List gateway policies for generation
  • Show me my gateway policies for generation for the DataPower api gateway
  • What are all the datapower nano gateway policies available for generation?

GatewayPolicyGenerator

Generates a DataPower API gateway and DataPower nano gateway documents from the available gateway policies. The output is displayed in the YAML format.

The following table describes the parameters for the DataPower nano gateway policies available for generation.

Table 3. Policy types and descriptions
Parameter Required Description
gatewayPolicies Yes List of gateway policies to include in the generated DataPower assembly.
gatewayType Yes Specifies the type of gateway for which to generate the document. Valid options are datapower-api-gateway or datapower-nano-gateway.
apiName No Applies for IBM API Studio only. If set, the API name specifies the document that it references.
project No Applies for IBM API Studio only. If set, the system adds the document to the specified project.
Example prompts

  • Create a datapower api gateway with the ratelimit, map and invoke gateway policies
  • Generate a datapower nano gateway with the invoke gateway policy for the project SampleProject
  • Define a datapower api gateway using the log policy for the api users-management and project UserServices

GatewayPolicyModifier

Modifies an existing DataPower assembly or FreeFlow policy sequence by applying specified gateway policies. Use only policies listed by ListGatewayPolicies. The updated document is displayed in YAML format.

The following table describes the parameters for the DataPowerAssemblyModifier.

Table 4. Policy types and descriptions
Parameter Required Description
gatewayPolicies Yes List of gateway policies to include in the generated DataPower assembly.
document Yes Specifies the type of document to attach.
gatewayType Yes Specifies type of gateway to modify the document. Valid options are datapower-api-gateway or datapower-nano-gateway.
apiName No Applies for IBM API Studio only. If set, links the DataPower assembly to the specified API name.
Example prompts

  • Add the datapower api gateway client-security and map policies to @da.yaml
  • Extend this datapower nano gateway document @sample-da.yaml with the invoke gateway policies for the api sample-api

SpectralRuleGenerator

Use this operation to convert a natural language description into a spectral rule in JSON format. The generated rule can be downloaded and added to a spectral ruleset for API governance. To improve accuracy, write clear, concise descriptions, include only one operation per prompt, and specify jsonPath fields when possible. For more information about using prompts, see guidelines for using prompts.

This operation displays the generated spectral rule in a JSON format that can be downloaded as a file.
Table 5. Policy types and descriptions
Parameter Required Description Default value
text Yes The natural language description of the spectral rule to generate None
Example prompts

  • Generate a spectral rule that ensures info.description must be at least 20 characters long
  • Generate a spectral rule that ensures all POST operations must have a request body defined
  • Generate a spectral rule that ensures info.title must not contain special characters
Next action suggested
  • Validate the generated rule: {@rule_file} with the openapi: {@openapi_file}
  • Create a ruleset in governance with the following rule: {@rule_file}
  • Add the rule to the ruleset {rulesetName:rulesetVersion}: {@rule_file}

OpenAPI Enhancer

The OpenAPI Enhancer tool communicates with the API Agent. After you enter a prompt and click Send in the API Agent, a proposed plan is displayed. To begin the specification enhancement or auto-correction of the OpenAPI, click Start. After the process is finished, you can download the improved OpenAPI file.
Key highlights
  • Enhance your OpenAPI 3.0 documentation by generating recommendations for your descriptions and examples.
  • Improves your OpenAPI 3.0 specification through identifying validation errors and generating potential corrections.
Table 6. Parameters
Parameter Required Description Default
input_file No The OpenAPI specification in YAML or JSON format. None
file_format No The format of the generated OpenAPI file that is displayed, either JSON or YAML. YAML
oai_feature_type Yes Select the type of GenAI enhancement that you want to apply, either suggest improvements or automatically correct the content. None
Specification enhancements
Enhance your OpenAPI documentation by analyzing the API definition, and generating recommendations for your descriptions and examples.
Example prompts

Augment the following openapi with enhanced descriptions and examples @openapi-sample.yaml
Note: Select the required file, for example, openapi-sample.yaml. Entering @ after the prompt displays a list of OpenAPI documents available in your workspace.
Specification validation errors
Improve your APIs by analyzing your OpenAPI 3.0 specification, and generating potential API corrections for any validation errors.
Example prompts

Correct the validation errors in the following openapi file @openapi-sample.yaml
Note:
  • By default, the format of the augmented OpenAPI document is YAML. If you need your OpenAPI document to be in JSON format, specify it clearly in the prompt.
  • These API Agent capabilities are also available in the API Manager UI.

OpenAPI Generator

The OpenAPI generator tool can be used to generate OpenAPI 3.0 documents in JSON or YAML format from scratch based on prompts that are provided by the user that uses Natural Language Processing (NLP). Given a natural language description of an API or application as input that the user would like to generate an OpenAPI document for, the tool uses the Granite 3 model available on IBM watsonx to generate a starter stub of an OpenAPI document that the user can then take and continue to build on.
Note: The tool generates an OpenAPI documents from a natural language description, whereas the OAS creator tool generates the OpenAPI documents from an existing database schema that added to the API Agent sources.
Tool details and limitations
The following are the Open API Generator tool details and limitations:
  • This tool is provided to assist users with the task of generating an OpenAPI document from scratch based on a natural language description, it should not be confused with the OAS creator tool, also available to the API Agent, which is used for generating an OpenAPI document from an existing database schema added to the API Agent sources.
  • This tool relies on the Granite 3 foundation model available IBM watsonx for OpenAPI document generation.
  • Given that this tool relies on the output of the foundation model based on the provided input description, like all AI models, the output is subject to errors.
  • If the generated OpenAPI document does not match the description that is provided as input, try again and consider rephrasing the description.
  • If the generated OpenAPI document that is displayed from the model contains errors, such as OpenAPI specification errors, or semantic errors, the tool automatically passes the document through the fix (auto-correct) operation of the OpenAPI Enhancer tool. If still errors are present after this correction, these will be reported in the chat window.

  • If the generated OpenAPI document contains JSON or YAML syntax errors that cannot be fixed (auto-corrected) by the OpenAPI Enhancer tool, the tool does not display the document. In this situation, the system displays the following message: please re-phrase and try again. Try rewording the input description before trying again, such as using a different ordering or combination of words in the input prompt.

  • All OpenAPI documents that are generated by this tool should be reviewed for correctness and accuracy before being used.
Generate an OpenAPI document from a natural language description
You can generate an OpenAPI 3.0 document from scratch in either JSON or YAML format, from a natural language description given in English (one or more sentences) for the API or application that you would like to generate. Simply start your chat prompt with Generate an openapi for.... The generated OpenAPI document contains component schemas relevant to the API or application that is described, and path items for create, retrieve, update, and delete operations for those schemas. Also, the generated document includes recommended operation-level security and security schemas by default, unless explicitly prompted not to do so.
Note: Break the prompt as multiple meaningful sentences. You can mention the type of API you want to generate in the first sentence and the required specifications in the following sentences.
This operation shows with the following details: The generated OpenAPI 3.0 document in JSON or YAML format (By default, if the YAML format not specified in the input prompt message) that can be downloaded.
Table 7. Parameters
Parameter Required Description Default
text Yes The natural language description of the OpenAPI 3.0 specification to be generated
Note:

The entire input prompt message is used as the text parameter value. It does not need to be referenced explicitly.

 None
file_format No The Open API Generator tool supports the output format of the generated OpenAPI document file in JSON and YAML. YAML
rulesets No List of rulesets to use when generating the Open API document. None
Example prompts

Generate an OpenAPI spec for a weather application

Generate an OpenAPI spec for a book library application

Generate an openapi for a blog application in yaml format

Generate an OpenAPI spec for a blog application. Include operations for searching for blogs by most recommended topics. Searching for blogs should not require any authentication

Generate an OpenAPI spec for a weather application. Include an operation to provide a 7-day forecast for a given location

Genrate an OpenAPI spec for a book library application. Include operations to add and remove books from the library. Also include an operation to search the books in the library with a title

Generate an OpenAPI spec for a book library application that complies with spectral-oas rulesets

Generate an OpenAPI spec for a book library application that complies with spectral-oas rulesets in json format
Next action suggested
  • Generate fastapi server code for the openapi file {@filename}
  • Generate fastapi server code with database integration for the openapi file {@filename}