[TT-16489] Created MCP definition ground work

[lghiur]

MCP Definition Structure

• Added mcpTools, mcpResources, and mcpPrompts to the OAS middleware schema
• Extended the Classic API Definition with jsonProtocol and isMCP fields
• Implemented OAS to Classic translation for MCP sections
• Maintains full backward compatibility with existing non-MCP APIs.

Ticket Details

TT-16489

Status	In Code Review
Summary	MCP definition data structure

Generated at: 2026-01-26 18:18:01

[probelabs]

This PR introduces the foundational data structures for Model Context Protocol (MCP) APIs. It extends the core API definition and the OpenAPI (OAS) specification to enable the configuration of MCP APIs, ensuring full backward compatibility with existing definitions.

Files Changed Analysis

• Total Changes: 8 files changed, with 642 additions and 42 deletions.
• Key Files:
  • apidef/api_definitions.go: The core APIDefinition struct is extended with JsonRpcVersion and ApplicationProtocol fields. New helper methods (IsMCP, MarkAsMCP) are added to identify and configure MCP APIs.
  • apidef/oas/middleware.go: The OAS middleware definition now includes mcpTools, mcpResources, and mcpPrompts. The ExtractTo method is updated to detect these sections and automatically mark the API as MCP.
  • apidef/oas/schema/*.json: The JSON schemas for the x-tyk-api-gateway extension are updated to reflect the new MCP fields.
• Notable Patterns: The majority of the new code consists of comprehensive unit tests (the new apidef/oas/mcp_test.go and additions to apidef/api_definitions_test.go), ensuring the new fields and translation logic are well-validated.

Architecture & Impact Assessment

• What this PR accomplishes: It lays the groundwork for supporting MCP APIs by enabling their definition and identification within Tyk. This is a preparatory step for implementing MCP-specific runtime logic.
• Key technical changes introduced:
  • API Definition Extension: Adds JsonRpcVersion and ApplicationProtocol to the APIDefinition struct.
  • OAS Specification Extension: Adds mcpTools, mcpResources, and mcpPrompts as valid properties within the x-tyk-api-gateway middleware object.
  • Automatic MCP Detection: The OAS import process now automatically identifies an API as MCP by calling MarkAsMCP() if any of the new MCP-related sections are present in its definition.
• Affected system components:
  • API Definition (apidef): The core data structure for APIs is modified.
  • OAS Importer (apidef/oas): The translation logic from OAS to Tyk's internal definition is updated.
  • This change has no impact on the gateway's runtime or request processing.

OAS to Classic API Definition Flow:

graph TD
    A["OAS Definition with x-tyk-api-gateway"] -- contains --> B{"mcpTools, mcpResources, or mcpPrompts"};
    B -- is processed by --> C["OAS Importer (middleware.ExtractTo)"];
    C -- if MCP section exists --> D["api.MarkAsMCP()"];
    D -- sets fields on --> E["Classic APIDefinition (ApplicationProtocol='mcp', JsonRpcVersion='2.0')"];

Loading

Scope Discovery & Context Expansion

• The scope of this PR is strictly limited to the API definition layer. It introduces no changes to runtime behavior, proxying, or middleware execution.
• A search for IsMCP confirms its usage is confined to the apidef package for definition handling and testing. To understand the full impact of this feature, the next step would be to look for subsequent work that consumes the new IsMCP() method in the gateway's request processing pipeline to implement MCP-specific logic.

Metadata

• Review Effort: 2 / 5
• Primary Label: feature

---

Powered by Visor from Probelabs

Last updated: 2026-01-26T16:08:29.528Z | Triggered by: pr_updated | Commit: 205d10c

💡 TIP: You can chat with Visor using /visor ask <your question>

[probelabs]

Security Issues (1)

Severity	Location	Issue
🟡 Warning	apidef/oas/middleware.go:23-29	The new fields `McpTools`, `McpResources`, and `McpPrompts` accept arbitrary string keys from the OAS API definition. The test case for `McpResources` uses a file URI (`file:///repo/*`), suggesting these keys might be used for resource lookups, such as file system access or network requests. This introduces a potential for Path Traversal, Server-Side Request Forgery (SSRF), or other injection attacks if the code that consumes these keys does not rigorously validate and sanitize them. 💡 Suggestion Ensure that any code using the keys from the `McpTools`, `McpResources`, and `McpPrompts` maps treats them as untrusted user input. Specifically, if these keys are used to construct file paths, URLs, or other resource identifiers, they must be strictly validated, sanitized, and constrained to prevent access to unintended resources. For file paths, canonicalize them and verify they are within a permitted base directory.

Architecture Issues (1)

Severity	Location	Issue
🟡 Warning	apidef/api_definitions.go:1441-1444	The `SetProtocol` function uses a generic `transport` parameter but assigns it to the specific `JsonRpcVersion` field. This creates a naming inconsistency that could be misleading if other transport protocols are introduced in the future, as the function would incorrectly populate a field named for JSON-RPC. 💡 Suggestion To improve design consistency and future extensibility, either rename the function to be more specific (e.g., `SetJsonRpcApplicationProtocol`) or generalize the struct field to match the function's generic nature (e.g., rename `JsonRpcVersion` to `TransportProtocolVersion`).

✅ Performance Check Passed

No performance issues found – changes LGTM.

✅ Quality Check Passed

No quality issues found – changes LGTM.

---

Powered by Visor from Probelabs

Last updated: 2026-01-26T16:08:32.846Z | Triggered by: pr_updated | Commit: 205d10c

💡 TIP: You can chat with Visor using /visor ask <your question>

[github-actions]

API Changes

--- prev.txt	2026-01-26 16:08:07.332218228 +0000
+++ current.txt	2026-01-26 16:07:57.448293984 +0000
@@ -84,6 +84,12 @@
 	OAuthAuthorizationTypeClientCredentials = "clientCredentials"
 	// OAuthAuthorizationTypePassword is the authorization type for password flow.
 	OAuthAuthorizationTypePassword = "password"
+
+	// JSON-RPC protocol versions
+	JsonRPC20 = "2.0"
+
+	// Application protocols
+	AppProtocolMCP = "mcp"
 )
 const (
 	GraphQLEngineDataSourceKindREST    = "REST"
@@ -184,6 +190,8 @@
 	ListenPort          int            `bson:"listen_port" json:"listen_port"`
 	Protocol            string         `bson:"protocol" json:"protocol"`
 	EnableProxyProtocol bool           `bson:"enable_proxy_protocol" json:"enable_proxy_protocol"`
+	JsonRpcVersion      string         `bson:"json_rpc_version,omitempty" json:"json_rpc_version,omitempty"`
+	ApplicationProtocol string         `bson:"application_protocol,omitempty" json:"application_protocol,omitempty"`
 	APIID               string         `bson:"api_id" json:"api_id"`
 	OrgID               string         `bson:"org_id" json:"org_id"`
 	UseKeylessAccess    bool           `bson:"use_keyless" json:"use_keyless"`
@@ -338,6 +346,13 @@
     hierarchy. A child API is identified by having a BaseID that differs from
     its own APIID.
 
+func (a *APIDefinition) IsMCP() bool
+    IsMCP returns true if this API uses the Model Context Protocol.
+
+func (a *APIDefinition) MarkAsMCP()
+    MarkAsMCP configures the API definition as a Model Context Protocol (MCP)
+    API.
+
 func (a *APIDefinition) Migrate() (versions []APIDefinition, err error)
 
 func (a *APIDefinition) MigrateAuthentication()
@@ -352,6 +367,9 @@
     SetDisabledFlags set disabled flags to true, since by default they are not
     enabled in OAS API definition.
 
+func (a *APIDefinition) SetProtocol(transport, application string)
+    SetProtocol configures the transport and application protocol for the API.
+
 type AnalyticsPluginConfig struct {
 	// Enabled activates the custom plugin
 	Enabled bool `bson:"enable" json:"enable,omitempty"`
@@ -3698,6 +3716,15 @@
 
 	// Operations contains configuration for middleware that can be applied to individual endpoints within the API (per-endpoint).
 	Operations Operations `bson:"operations,omitempty" json:"operations,omitempty"`
+
+	// McpTools contains configuration for middleware that can be applied to MCP tools.
+	McpTools map[string]*Operation `bson:"mcpTools,omitempty" json:"mcpTools,omitempty"`
+
+	// McpResources contains configuration for middleware that can be applied to MCP resources.
+	McpResources map[string]*Operation `bson:"mcpResources,omitempty" json:"mcpResources,omitempty"`
+
+	// McpPrompts contains configuration for middleware that can be applied to MCP prompts.
+	McpPrompts map[string]*Operation `bson:"mcpPrompts,omitempty" json:"mcpPrompts,omitempty"`
 }
     Middleware holds configuration for Tyk's native middleware.
 

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud