[Bug]: MCP Tool outputSchema Field is Stripped During Discovery

[crivetimihai]

Bug Description

ContextForge strips the outputSchema field from MCP tools during gateway discovery, breaking structured content support and MCP spec compliance.

MCP Specification Context

Per the MCP Tools Specification (2025-06-18):

Tools may also provide an output schema for validation of structured results. If an output schema is provided:

• Servers MUST provide structured results that conform to this schema.
• Clients SHOULD validate structured results against this schema.

The outputSchema field is part of the official Tool definition:

interface Tool {
  name: string;
  description?: string;
  inputSchema: JSONSchema;
  outputSchema?: JSONSchema;  // ← This is being stripped
  annotations?: ToolAnnotations;
}

How FastMCP Uses outputSchema

Modern MCP servers built with FastMCP automatically generate outputSchema from function return type annotations:

@server.tool()
def get_weather_data(location: str) -> WeatherData:
    """Returns structured weather data."""
    return WeatherData(temperature=22.5, conditions="Partly cloudy", humidity=65)

FastMCP generates:

{
  "name": "get_weather_data",
  "inputSchema": { "type": "object", "properties": { "location": { "type": "string" } } },
  "outputSchema": {
    "type": "object",
    "properties": {
      "temperature": { "type": "number" },
      "conditions": { "type": "string" },
      "humidity": { "type": "number" }
    },
    "required": ["temperature", "conditions", "humidity"]
  }
}

The tool then returns BOTH unstructured and structured content:

{
  "content": [{ "type": "text", "text": "{\"temperature\": 22.5, ...}" }],
  "structuredContent": { "temperature": 22.5, "conditions": "Partly cloudy", "humidity": 65 }
}

The Bug in ContextForge

Location: mcpgateway/services/gateway_service.py:2866-2868

response = await session.list_tools()
tools = response.tools
tools = [tool.model_dump(by_alias=True, exclude_none=True) for tool in tools]  # Has outputSchema ✅
tools = [ToolCreate.model_validate(tool) for tool in tools]  # Strips outputSchema ❌

Root Cause

The ToolCreate, ToolUpdate, and ToolRead schemas in mcpgateway/schemas.py do NOT include an output_schema field:

class ToolCreate(BaseModel):
    name: str
    description: Optional[str]
    input_schema: Optional[Dict[str, Any]] = Field(..., alias="inputSchema")
    # ❌ NO output_schema field
    annotations: Optional[Dict[str, Any]]

When ToolCreate.model_validate(tool) is called, Pydantic silently drops the outputSchema field because it's not defined in the schema.

Similarly, the database Tool model has no output_schema column to store this data.

Impact

1. Loss of Type Information: Clients and LLMs cannot understand what structured data format tools return
2. No Response Validation: Cannot validate tool responses against expected schemas
3. Breaks MCP Spec Compliance: Tools advertising outputSchema lose that metadata when proxied through ContextForge
4. Poor Developer Experience: No autocomplete, type hints, or documentation for tool outputs
5. Breaks Structured Workflows: Modern AI agents rely on typed tool outputs for reliable automation

Evidence from MCP SDK

The official MCP Python SDK types show outputSchema is a standard field:

# From mcp/types.py
class Tool(BaseMetadata):
    """Definition for a tool the client can call."""
    description: str | None = None
    inputSchema: dict[str, Any]
    outputSchema: dict[str, Any] | None = None  # ← Official field
    icons: list[Icon] | None = None
    annotations: ToolAnnotations | None = None

Expected Behavior

ContextForge should:

1. Preserve outputSchema when discovering tools from MCP servers
2. Store outputSchema in the database alongside input_schema
3. Return outputSchema in API responses (/tools, /servers/{id}/tools, etc.)
4. Pass through structuredContent from tool invocations
5. Optionally validate structuredContent against outputSchema (per spec: "Clients SHOULD validate")

Proposed Solution

Add output_schema field (with alias outputSchema) to:

1. Database Model (mcpgateway/db.py):

   class Tool(Base):
       # ...
       input_schema = Column(JSON, nullable=False)
       output_schema = Column(JSON, nullable=True)  # ← Add this

2. Pydantic Schemas (mcpgateway/schemas.py):

   class ToolCreate(BaseModel):
       input_schema: Dict[str, Any] = Field(..., alias="inputSchema")
       output_schema: Optional[Dict[str, Any]] = Field(None, alias="outputSchema")  # ← Add
   
   class ToolRead(BaseModel):
       input_schema: Dict[str, Any]
       output_schema: Optional[Dict[str, Any]]  # ← Add
   
   class ToolUpdate(BaseModel):
       input_schema: Optional[Dict[str, Any]]
       output_schema: Optional[Dict[str, Any]]  # ← Add

3. Database Migration (Alembic):

   ALTER TABLE tools ADD COLUMN output_schema JSON NULL;

Reproduction Steps

1. Create an MCP server with FastMCP that uses typed return annotations:

   @server.tool()
   def structured_tool(x: int) -> dict[str, int]:
       return {"result": x * 2}

2. Register the server as a gateway in ContextForge

3. Query GET /tools or GET /servers/{id}/tools

4. Observe: The returned tool definition has inputSchema but NOT outputSchema

Additional Context

• This affects all modern FastMCP servers (FastMCP automatically generates outputSchema)
• The MCP 2025-06-18 specification explicitly includes outputSchema
• Structured outputs are becoming standard in AI workflows for reliability
• ContextForge already stores input_schema in the database, so adding output_schema is a natural extension

Labels

• bug: Core functionality (MCP spec compliance) is broken
• enhancement: Adds missing feature support
• mcp-protocol: Related to MCP specification adherence
• python: Python codebase changes required

Priority

High - This breaks a core MCP specification feature that modern servers rely on.

[crivetimihai]

Additional Findings

Here are ALL locations that need to be updated to support outputSchema:

---

📍 Code Locations Requiring Changes

1. Database Model (mcpgateway/db.py)

Current (line 1572):

input_schema: Mapped[Dict[str, Any]] = mapped_column(JSON)

Add After:

output_schema: Mapped[Optional[Dict[str, Any]]] = mapped_column(JSON, nullable=True)

Validation Function (line 3182-3186) - ADD output_schema validation:

def validate_tool_schema(mapper, connection, target):
    """Validate tool input and output schemas are valid JSON Schema."""
    if hasattr(target, "input_schema"):
        try:
            jsonschema.Draft7Validator.check_schema(target.input_schema)
        except jsonschema.exceptions.SchemaError as e:
            raise ValueError(f"Invalid tool input schema: {str(e)}") from e
    
    # ADD THIS:
    if hasattr(target, "output_schema") and target.output_schema is not None:
        try:
            jsonschema.Draft7Validator.check_schema(target.output_schema)
        except jsonschema.exceptions.SchemaError as e:
            raise ValueError(f"Invalid tool output schema: {str(e)}") from e

---

2. Pydantic Schemas (mcpgateway/schemas.py)

ToolCreate (line 379)

Add field:

class ToolCreate(BaseModel):
    # ... existing fields ...
    input_schema: Optional[Dict[str, Any]] = Field(
        default_factory=lambda: {"type": "object", "properties": {}}, 
        description="JSON Schema for validating tool parameters", 
        alias="inputSchema"
    )
    output_schema: Optional[Dict[str, Any]] = Field(
        None, 
        description="JSON Schema for validating tool output structure", 
        alias="outputSchema"
    )  # ADD THIS
    annotations: Optional[Dict[str, Any]] = Field(...)

ToolRead (line 1013)

Add field:

class ToolRead(BaseModelWithConfigDict):
    # ... existing fields ...
    input_schema: Dict[str, Any]
    output_schema: Optional[Dict[str, Any]]  # ADD THIS
    annotations: Optional[Dict[str, Any]]

ToolUpdate (line 878)

Add field:

class ToolUpdate(BaseModel):
    # ... existing fields ...
    input_schema: Optional[Dict[str, Any]]
    output_schema: Optional[Dict[str, Any]]  # ADD THIS
    annotations: Optional[Dict[str, Any]]

---

3. Gateway Service (mcpgateway/services/gateway_service.py)

THREE locations where tools are discovered from MCP servers:

Location 1: connect_to_sse_server_after_oauth (lines 2864-2868)

Location 2: connect_to_sse_server (lines 2959-2963)

Location 3: connect_to_streamablehttp_server (lines 3053-3057)

Current pattern (all 3 locations):

response = await session.list_tools()
tools = response.tools
tools = [tool.model_dump(by_alias=True, exclude_none=True) for tool in tools]  # ✅ Has outputSchema
tools = [ToolCreate.model_validate(tool) for tool in tools]  # ❌ Strips outputSchema

No code change needed - once ToolCreate schema is updated, these will automatically preserve outputSchema.

---

4. Tool Service (mcpgateway/services/tool_service.py)

register_tool method (line 469)

Add:

db_tool = DbTool(
    # ... existing fields ...
    input_schema=tool.input_schema,
    output_schema=tool.output_schema,  # ADD THIS
    annotations=tool.annotations,
    # ... rest of fields ...
)

_convert_tool_to_read method (line 291)

Already handles all fields via tool.__dict__.copy() - no change needed if DB model is updated.

update_tool method (line 1237)

Add:

if tool_update.input_schema is not None:
    tool.input_schema = tool_update.input_schema
if tool_update.output_schema is not None:  # ADD THIS
    tool.output_schema = tool_update.output_schema
if tool_update.annotations is not None:
    tool.annotations = tool_update.annotations

---

5. Import Service (mcpgateway/services/import_service.py)

_convert_to_tool_create method (lines 948-958)

Add:

return ToolCreate(
    name=tool_data["name"],
    displayName=tool_data.get("displayName"),
    url=tool_data["url"],
    description=tool_data.get("description"),
    integration_type=tool_data.get("integration_type", "REST"),
    request_type=tool_data.get("request_type", "GET"),
    headers=tool_data.get("headers"),
    input_schema=tool_data.get("input_schema"),
    output_schema=tool_data.get("output_schema"),  # ADD THIS
    annotations=tool_data.get("annotations"),
    # ... rest of fields ...
)

_convert_to_tool_update method (lines 982-986)

Add:

return ToolUpdate(
    # ... existing fields ...
    input_schema=tool_data.get("input_schema"),
    output_schema=tool_data.get("output_schema"),  # ADD THIS
    annotations=tool_data.get("annotations"),
    # ... rest of fields ...
)

---

6. Export Service (mcpgateway/services/export_service.py)

export_tools method (line 296)

Add:

"description": tool.description,
"headers": tool.headers or {},
"input_schema": tool.input_schema or {"type": "object", "properties": {}},
"output_schema": tool.output_schema,  # ADD THIS
"annotations": tool.annotations or {},

---

7. Admin UI (mcpgateway/admin.py)

handle_create_tool_form (lines 5048-5061)

Add:

headers_raw = form.get("headers")
input_schema_raw = form.get("input_schema")
output_schema_raw = form.get("output_schema")  # ADD THIS
annotations_raw = form.get("annotations")

tool_data: dict[str, Any] = {
    "name": form.get("name"),
    "url": form.get("url"),
    # ... existing fields ...
    "input_schema": json.loads(input_schema_raw if isinstance(input_schema_raw, str) and input_schema_raw else "{}"),
    "output_schema": json.loads(output_schema_raw if isinstance(output_schema_raw, str) and output_schema_raw else "{}"),  # ADD THIS
    "annotations": json.loads(annotations_raw if isinstance(annotations_raw, str) and annotations_raw else "{}"),
    # ... rest of fields ...
}

handle_edit_tool_form (lines 5305-5319)

Add:

headers_raw2 = form.get("headers")
input_schema_raw2 = form.get("input_schema")
output_schema_raw2 = form.get("output_schema")  # ADD THIS
annotations_raw2 = form.get("annotations")

tool_data: dict[str, Any] = {
    # ... existing fields ...
    "input_schema": json.loads(input_schema_raw2 if isinstance(input_schema_raw2, str) and input_schema_raw2 else "{}"),
    "output_schema": json.loads(output_schema_raw2 if isinstance(output_schema_raw2, str) and output_schema_raw2 else "{}"),  # ADD THIS
    "annotations": json.loads(annotations_raw2 if isinstance(annotations_raw2, str) and annotations_raw2 else "{}"),
    # ... rest of fields ...
}

Note: The Admin UI HTML templates will also need to add an output_schema form field.

---

🗄️ Database Migration

Alembic Migration Script

Create: mcpgateway/alembic/versions/XXXXXX_add_output_schema_to_tools.py

# -*- coding: utf-8 -*-
"""add output_schema to tools

Revision ID: XXXXXX
Revises: f8c9d3e2a1b4
Create Date: 2025-XX-XX XX:XX:XX.XXXXXX
"""

from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa

revision: str = "XXXXXX"
down_revision: Union[str, Sequence[str], None] = "f8c9d3e2a1b4"
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None


def upgrade() -> None:
    """Add output_schema column to tools table."""
    inspector = sa.inspect(op.get_bind())
    tables = inspector.get_table_names()

    if "tools" not in tables:
        print("Fresh database detected. Skipping migration.")
        return

    # Check if column already exists
    columns = [col["name"] for col in inspector.get_columns("tools")]
    if "output_schema" in columns:
        print("output_schema column already exists. Skipping migration.")
        return

    # Detect database type
    connection = op.get_bind()
    dialect_name = connection.dialect.name

    try:
        if dialect_name == "sqlite":
            # SQLite: Use batch mode for ALTER TABLE
            with op.batch_alter_table("tools", schema=None) as batch_op:
                batch_op.add_column(
                    sa.Column(
                        "output_schema",
                        sa.JSON(),
                        nullable=True,
                        comment="JSON Schema for validating tool output structure returned in structuredContent"
                    )
                )
            print("Successfully added output_schema column to tools table (SQLite).")

        elif dialect_name == "postgresql":
            # PostgreSQL: Direct ALTER TABLE with JSONB
            op.execute("""
                ALTER TABLE tools 
                ADD COLUMN output_schema JSONB NULL
            """)
            op.execute("""
                COMMENT ON COLUMN tools.output_schema IS 
                'JSON Schema for validating tool output structure returned in structuredContent'
            """)
            print("Successfully added output_schema column to tools table (PostgreSQL).")

        elif dialect_name in ("mysql", "mariadb"):
            # MySQL/MariaDB: Use JSON type
            op.execute("""
                ALTER TABLE tools 
                ADD COLUMN output_schema JSON NULL 
                COMMENT 'JSON Schema for validating tool output structure returned in structuredContent'
            """)
            print("Successfully added output_schema column to tools table (MySQL/MariaDB).")

        else:
            # Fallback for other databases
            with op.batch_alter_table("tools", schema=None) as batch_op:
                batch_op.add_column(
                    sa.Column("output_schema", sa.JSON(), nullable=True)
                )
            print(f"Successfully added output_schema column to tools table ({dialect_name}).")

    except Exception as e:
        print(f"Warning: Could not add output_schema column to tools: {e}")
        raise


def downgrade() -> None:
    """Remove output_schema column from tools table."""
    inspector = sa.inspect(op.get_bind())
    tables = inspector.get_table_names()

    if "tools" not in tables:
        return

    columns = [col["name"] for col in inspector.get_columns("tools")]
    if "output_schema" not in columns:
        print("output_schema column does not exist. Nothing to remove.")
        return

    dialect_name = op.get_bind().dialect.name

    try:
        if dialect_name == "sqlite":
            with op.batch_alter_table("tools", schema=None) as batch_op:
                batch_op.drop_column("output_schema")
        else:
            op.drop_column("tools", "output_schema")
        
        print(f"Successfully removed output_schema column from tools table ({dialect_name}).")
    except Exception as e:
        print(f"Warning: Could not remove output_schema column from tools: {e}")
        raise

Database-Specific Notes

SQLite

• Uses JSON type (stored as TEXT, validated on insert/update)
• Requires batch_alter_table for ALTER operations
• No native JSONB, but JSON validation is performed

PostgreSQL

• Uses JSONB type (binary JSON, indexed, efficient)
• Supports GIN indexes for querying JSON fields
• Column comments supported via COMMENT ON COLUMN

MySQL/MariaDB

• Uses JSON type (native since MySQL 5.7.8, MariaDB 10.2.7)
• JSON validation enforced at database level
• Column comments via COMMENT in ALTER TABLE

---

📝 Summary

Total Files to Modify: 7

1. mcpgateway/db.py - Database model + validation
2. mcpgateway/schemas.py - 3 schemas (ToolCreate, ToolRead, ToolUpdate)
3. mcpgateway/services/tool_service.py - register_tool, update_tool methods
4. mcpgateway/services/import_service.py - 2 conversion methods
5. mcpgateway/services/export_service.py - export_tools method
6. mcpgateway/admin.py - 2 form handlers (+ HTML templates)
7. mcpgateway/alembic/versions/XXXXXX_*.py - New migration

Total Lines Changed: ~50-60 lines across 7 files

Breaking Changes: None (backward compatible - nullable field)

Testing Required:

• Tool discovery from FastMCP servers with outputSchema
• Tool registration/update with outputSchema
• Import/export with outputSchema
• Database migration on SQLite, PostgreSQL, MySQL
• Admin UI forms for creating/editing tools

---

✅ Validation Checklist

• All 3 gateway discovery paths preserve outputSchema
• Tool registration stores outputSchema in database
• Tool updates can modify outputSchema
• Tool listings return outputSchema in API responses
• Import/export handles outputSchema correctly
• Admin UI displays and edits outputSchema
• Database migration works on all supported databases
• Schema validation works for both input and output schemas
• Existing tools without outputSchema continue to work (NULL handling)

[rakdutta]

UI Enhancement: Add output_schema Field in Admin Templates and Update admin.js Handling

Description

The Admin UI should support configuration and rendering of the output_schema field for tools, similar to how the existing input_schema is handled.
This enhancement ensures both create/edit forms and the tool detail view display and manage output schemas consistently.

---

1️⃣ Template Updates

File: /mcpgateway/templates/admin.html

Add after line 3091 (after input_schema div):

<div>
  <label
    class="block text-sm font-medium text-gray-700 dark:text-gray-400"
    >Output Schema (JSON)</label
  >
  <textarea
    name="output_schema"
    id="output-schema-editor"
    rows="6"
    placeholder='{"type":"object","properties":{"result":{"type":"string"}}}'
    class="mt-1 block w-full rounded-md border border-gray-300 dark:border-gray-700 shadow-sm focus:border-indigo-500 focus:ring-indigo-500 dark:bg-gray-900 dark:placeholder-gray-300 dark:text-gray-300"
  ></textarea>
  <p class="mt-1 text-xs text-gray-500 dark:text-gray-400">
    Optional JSON Schema describing the expected output/response from this tool.
  </p>
</div>

Add after line 6561 (after input_schema div in edit form):

<div>
  <label
    class="block text-sm font-medium text-gray-700 dark:text-gray-300"
    >Output Schema (JSON)</label
  >
  <textarea
    name="output_schema"
    id="edit-tool-output-schema"
    class="mt-1 block w-full rounded-md border border-gray-300 dark:border-gray-600 shadow-sm focus:border-indigo-500 focus:ring-indigo-500 dark:bg-gray-900 dark:placeholder-gray-300 dark:text-gray-300"
  ></textarea>
  <p class="mt-1 text-xs text-gray-500 dark:text-gray-400">
    Optional JSON Schema describing the tool's output/response.
  </p>
</div>

---

2️⃣ JavaScript Updates

File: /mcpgateway/static/js/admin.js
Functions affected:

• editTool(toolId)
• viewTool(toolId)
• handleToolFormSubmit(event)
• handleEditToolFormSubmit(event)
• setupFormValidation()
• initializeCodeMirrorEditors()
• New function: setupOutputSchemaValidation()

3️⃣ New Validation Logic

A new helper function setupOutputSchemaValidation() has been added to provide live JSON validation and visual feedback for both add and edit forms.

It:

• Adds inline JSON validation below the output schema fields.
• Supports both CodeMirror editor and plain <textarea> fallback.
• Shows real-time "Valid JSON" or error messages with color-coded status indicators.

---

4️⃣ CodeMirror Editor Configuration

Two new CodeMirror editors were registered:

{
  id: "output-schema-editor",
  mode: "application/json",
  varName: "outputSchemaEditor",
},
{
  id: "edit-tool-output-schema",
  mode: "application/json",
  varName: "editToolOutputSchemaEditor",
}

These ensure syntax highlighting, JSON validation, and editing parity with the input schema editors.

---

5️⃣ Expected Outcome

✅ Admin UI now supports both input and output schema configuration.
✅ viewTool() robustly handles multiple output schema naming conventions (tool.outputSchema, tool.output_schema, tool.output).
✅ Live JSON validation provides user feedback on schema correctness.
✅ Output schema safely displayed under Technical Details with consistent styling.

---

7️⃣ Testing Steps

1. Add New Tool → Verify Output Schema (JSON) field appears after Input Schema.
2. Edit Tool → Confirm both schemas load correctly and validate live.
3. View Tool Details → Ensure output schema displays formatted JSON.
4. Test saving, refreshing, and reloading to confirm persisted values.