Governance MCP

The Governance MCP tool validates spectral rules against OpenAPI definitions, create rulesets, and update existing rulesets for API governance.

The Governance MCP tool supports the following operations:

Spectral rule validator

Validate a spectral rule against an OpenAPI definition. Provide a spectral rule file in JSON or YAML format and an optional OpenAPI file. If you do not provide an OpenAPI file, the tool can generate one that violates the rule to confirm the rule works as expected.

The validation result includes details about failed rules and errors. The output is displayed in a CSV file.

Table 1. Parameters
Parameter Required Description Default value
rule_file Yes The spectral rule file to validate. None
openapi_file No The OpenAPI file to validate against. None
Example prompts

  • With OpenAPI file:
    Validate the generated rule: {@rule_file} with the OpenAPI: {@openapi_file}.
  • Prompt to auto generate OpenAPI file:
    Validate this rule: {@rule_file} with an internal OpenAPI expected to fail the rule.

Create ruleset with a spectral rule

Create a new ruleset in the Governance MCP tool with the specified rule.
Table 2. Parameters
Parameter Required Description Default value
rule_file Yes The spectral rule file to validate. None
rulesetName No The name of the ruleset to create. custom-(uuid)
rulesetVersion No The version of the ruleset to create. 1.0.0
Example prompts

  • Create a ruleset in governance with the following rule: {@rule_file}
  • Create a ruleset in governance with the given rule {@rule_file} and ruleset name as validation-ruleset and ruleset version 1.0.0

Governance MCP ruleset creator

This operation creates a new ruleset in the Governance MCP tool with the ruleset that is passed to it.

Table 3. Parameters
Parameter Required Description Default value
ruleset Yes The ruleset is to be created in JSON or YAML format None
Example prompts

  • Add the following ruleset to the governance service [@ruleset_file]
  • Create the ruleset in the governance service [@ruleset_file]

Governance MCP ruleset updater

Update an existing ruleset in the Governance MCP tool. You can use this operation to complete the following actions:

  • Update the ruleset title and description.
  • Add a new rule or update an existing rule in the ruleset.
  • Change the ruleset state to publish or archive.
  • Delete a rule from the ruleset.
Table 4. Parameters
Parameter Required Description Default value
rulesetName Yes The name of the ruleset to update. None
rulesetVersion No The version of the ruleset to update. None
rule_file No The spectral rule to add to the ruleset. None
ruleNameToDelete No The name of the rule to update. None
newRulesetState No The state of the rule to update. None
newRulesetTitle No The title of the ruleset to update. None
newRulesetDescription No The description of the ruleset to update. None
Example prompts

  • Add this rule [@rule_file] to ruleset my_ruleset:1.0.0
  • Update the ruleset my_ruleset with the following rule: {@rule_file}
  • Update the ruleset my_ruleset with the description `updated and new description`
  • Publish the ruleset my_ruleset:1.0.0
  • Archive the ruleset my_ruleset:1.0.0

List Rulesets

You can list the spectral rulesets that are provided to you as part of Governance within your provider organization.

A table displays the following details about the rulesets:
  • Name
  • Version
  • Description
Example prompt

List rulesets
Next action suggested
  • Validate api {@filename} by using ruleset {ruleset}

List rules in a Ruleset

You can list all the individual rules that are part of the spectral rulesets available to you within your provider organization.

  • A table shows the following details about each rule within the specified ruleset:
    • Name
    • Description
Table 5. Parameters
Parameter Required Description Default
ruleset Yes The ruleset name, which you want to list the rules for. None
Example prompt

List rules in ruleset {ruleset}
Next action suggested
  • Validate api {@filename} by using ruleset {ruleset}

Validate an OpenAPI document by using rulesets

You can validate OpenAPI documents with spectral rulesets in your provider organization with the following options:
  • Using a local file attachment upload in the Visual Studio Code plug-in chat window.
  • Providing the name and version of an existing API within the provider organization of the user on the API Manager.

This operation displays the following details:

  • A brief summary of the number of spectral findings and their severity.
  • A validation report .CSV file that can be downloaded, containing the complete set of the following findings:
    • Rule and ruleset of the rule
    • A message that describes the validation finding that violates the rule.
    • Line number in the OpenAPI document corresponds to the finding.
    • Location (JSON path) of the finding within the OpenAPI document.
  • The findings and their locations also open in the PROBLEMS panel, as shown in following screenshot.

  • If the OpenAPI document is a local file, it automatically opens in the Visual Studio Code file editor. All spectral findings are highlighted in the file.
Table 6. Parameters
Parameter Required Description Default
input_file No The OpenAPI specification in YAML or JSON format to be validated. None
ruleset Yes List of rulesets to use in the validation. None
Example prompts

To validate a local file against a single Ruleset, run the following prompt:
validate api {@filename} using {ruleset} ruleset
To validate a local file against two or more Rule sets, run the following prompt:
Validate api {@filename} using rulesets {ruleset-1}, {ruleset-2}
Next action suggested
  • Remediate api {@filename} by using ruleset {ruleset}
  • Revalidate api {@filename} by using ruleset {ruleset}

Remediate (fix) an OpenAPI document that uses rulesets

If Governance validation of an OpenAPI document reveals findings based on spectral rulesets within your provider organization, you can use AI-based remediation to attempt to resolve these findings. Upload a local file in the Visual Studio Code plug-in chat window or specify an existing API on the API Manager.

This operation displays the following details:

  • An OpenAPI document file that can be downloaded that contains all the applied remediation that the AI-based remediation was able to fix automatically for the chosen rulesets.

  • Also, the remediated OpenAPI document file automatically opens in the Visual Studio Code file editor. The applied fixes get highlighted directly in the file.

  • The following details of each applied fix are shown in the AI RECOMMENDATIONS panel:

    • Path (JSON Path) to the recommendation
    • Recommendation (a description)
    • Explanation (explains the recommendation)
    • Details of the Spectral Rule that the recommendation comes from (Severity, Ruleset name, Rule name, and message).
Note:
  • The AI-based remediation is only supported for the spectral-owasp and spectral-oas rulesets from Governance. If prompted to remediate by using an unsupported ruleset, you receive a warning that the unsupported ruleset was not used in the chat response from the API Agent.
  • The tool expects that a valid OpenAPI 3.0 document is used as input. No warning is given if an invalid file is supplied. For example, supplying an AsyncAPI document as input against a ruleset with rules that apply to an OpenAPI document, and vice-versa.
  • You can run remediation multiple times on the same OpenAPI document to remediate an issue if it is not found initially.
  • Applying fixes through AI can introduce new violations of other spectral rules because the system does not automatically validate its fixes and recommendations against the rulesets after each change.
Table 7. Parameters
Parameter Required Description Default
input_file No The OpenAPI Specification in YAML or JSON format to be remediated. None
ruleset Yes List of rulesets to use in the remediation. None
Example prompts

To remediate a local file against a ruleset, run the following prompt:
Remediate api {@filename} using {ruleset} ruleset
To remediate a local file against two or more Rulesets, run the following prompt:
Remediate api {@filename} using rulesets {ruleset-1}, {ruleset-2}