The api.routes configuration determines which operations from the OpenAPI specification are exposed as tools. If this section is omitted, non-GET methods are excluded by default, resulting in read-only behavior. This subgroup control exposure of API operations through inclusion and exclusion rules.

The api.routes configuration contains several subsections that define how operations are filtered and tagged. Each subsection serves a specific purpose in controlling API exposure:
  • maps—Orders INCLUDE or EXCLUDE rules for paths and methods.
  • entity_rules—Attaches entity:* tags based on path patterns for better catalog grouping.
  • tags—Injects additional tags for operations by path and optional method list.
  • exclude_tool_name_patterns—Applies fnmatch patterns after OpenAPI load to remove generated tools by name. Useful for removing duplicate management endpoints or experimental operations without altering the upstream specification.
The system evaluates rules in the order they appear. The first matching rule is applied. It is recommended that you keep the rule set concise and provide explicit INCLUDE rules for any write operations that you want to expose intentionally.

Processing pipeline

The system processes operations in three stages:
  1. Route maps apply early filtering based on path, method, and tags.
  2. Tools are generated from the remaining operations.
  3. Pattern filtering removes tools by name using the exclude_tool_name_patterns property.

Tag processing in route maps

The MCP server automatically generates normalized tags from the OpenAPI specification. For example, "APSV Transport" becomes "group:apsv-transport". It is recommended to use these generated tag names in route map filters, and not the original OpenAPI tag names. Normalization ensures consistency by converting original OpenAPI tags into a predictable format. The following examples show how to configure route maps using normalized tags and inclusion or exclusion rules.
  • Allow two POST endpoints while blocking others:
    {
  "api": {
    "routes": {
      "maps": [
        { "methods": ["POST"], "path": "/orders/**", "mcp_type": "INCLUDE" },
        { "methods": ["POST"], "mcp_type": "EXCLUDE" }  
      ],
      "entity_rules": [ { "entity": "order", "path_prefix": "/orders" } ]
    }
  }
}
  • Exclude operations by auto-generated tags:
    {
  "api": {
    "routes": {
      "maps": [
        { 
          "comment": "Exclude SOAP operations",
          "tags": ["group:soap-transport"],
          "mcp_type": "EXCLUDE" 
        },
        { 
          "comment": "Allow all other operations",
          "methods": ["GET","POST","PUT","DELETE","PATCH"], 
          "mcp_type": "TOOL" 
        }
      ]
    }
  }
}

OperationId deduplication

The server automatically detects and resolves duplicate operationId values in OpenAPI specs before tool generation. When the system finds duplicates, it renames them by prefixing normalized tag names. For example:
getMetrics + getMetrics is changed to getMetrics + soap-transport-getMetrics

This approach ensures unique tool names without overwriting. No configuration is required for this process.

Tool name filtering

Some OpenAPI generators emit unwanted operations or leave residual duplicates. The server provides post-generation filtering using exclude_tool_name_patterns. This property accepts an array of fnmatch patterns such as "*_1", "*_2", or "resetMetrics_*". For example:
{
  "api": {
    "routes": {
      "maps": [
        { "path": "/**", "mcp_type": "INCLUDE" },
        { "methods": ["DELETE"], "path": "/oemanager/rest/oeservices/unpublishService/**", "mcp_type": "EXCLUDE" },
        { "methods": ["DELETE"], "path": "/oemanager/soap/oeservices/unpublishService/**", "mcp_type": "EXCLUDE" }
      ],
      "exclude_tool_name_patterns": ["*_1", "*_2"]
    }
  }
}
The following points summarize the operational behavior and recommendations for tool name filtering:
  • Processing order—The system applies route maps first to filter operations. After that, pattern-based filtering removes tools by name.
  • Tag conflicts—When using both tag-based exclusions and pattern filtering, verify that patterns do not remove tools before tag exclusions can take effect.
  • Path-based exclusions—Use EXCLUDE rules based on paths early in the pipeline to reduce the surface area of operations.
  • Post-registration filtering—Name pattern filtering occurs after tool registration. Tools removed by patterns do not appear in discovery or inventory logs.
  • Preferred approach—Deduplicate operationId values in the OpenAPI specification whenever possible. Pattern filtering should be treated as a temporary, non-invasive solution.
  • Pattern list size—Keep the pattern list short. Avoid overly broad patterns such as *Service* because they may hide required tools.
  • Verification—At startup, the startup logger (INFO level) reports the number of tools removed by name patterns using the message Filtered tools by name patterns removed=<N>. For detailed inventory logs, set logging.loggers.startup=DEBUG.