openapi: 3.2.0
info:
  title: AI Gateway MCP Server Tools API
  description: Universal MCP Gateway with OAuth integration - Modern Architecture
  version: 2.0.3290
tags:
- name: Tools
paths:
  /tools/call:
    post:
      summary: Call Tool
      description: Direct tool call endpoint with unified authentication
      operationId: call_tool_tools_call_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolCallRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Tools
  /tools/list:
    get:
      summary: List Tools
      description: 'List available tools, filtered to the caller''s role.


        SECURITY: pre-2.0.938 this endpoint was unauthenticated and returned

        the full tool inventory regardless of caller. A guest invited to a

        single service could enumerate every other service-action tool name

        — useful pretexting / phishing surface, and inconsistent with the

        MCP ``tools/list`` handler which already role-filters via

        ``deny_reason_for_tool``. This handler now mirrors that behaviour:

        require authentication, then drop any tool the caller could not

        actually invoke.'
      operationId: list_tools_tools_list_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Tools
  /v1/tools/execute/async:
    post:
      summary: Execute Tool Async
      description: 'POST /v1/tools/execute/async


        Start asynchronous tool execution with polling support.

        Returns 202 Accepted with Location header pointing to status endpoint.


        Request Body:

        {

        "tool": "gitlab_read_actions",

        "arguments": {"message": "Show me GitLab features"}

        }


        Response (202 Accepted):

        {

        "task_id": "abc123",

        "status": "analyzing",

        "status_url": "/v1/tools/status/abc123",

        "message": "Task accepted for processing"

        }'
      operationId: execute_tool_async_v1_tools_execute_async_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Tools
  /v1/tools/status/{task_id}:
    get:
      summary: Get Task Status
      description: 'GET /v1/tools/status/{task_id}


        Poll task status and get progress updates.


        Response (In Progress - 200 OK):

        {

        "task_id": "abc123",

        "status": "fetching",

        "progress": 50,

        "service": "gitlab",

        "message": "📡 Fetching data from GitLab...",

        "created_at": 1698765432.123,

        "updated_at": 1698765433.456

        }


        Response (Complete - 200 OK):

        {

        "task_id": "abc123",

        "status": "complete",

        "progress": 100,

        "message": "✅ Query completed successfully",

        "result": {...},

        "created_at": 1698765432.123,

        "updated_at": 1698765437.890

        }'
      operationId: get_task_status_v1_tools_status__task_id__get
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Tools
  /v1/tools/stats:
    get:
      summary: Get Storage Stats Endpoint
      description: 'GET /v1/tools/stats (Debug endpoint)


        Get storage statistics for monitoring


        Response:

        {

        "total_tasks": 5,

        "status_counts": {

        "analyzing": 1,

        "fetching": 2,

        "complete": 2,

        "error": 0

        },

        "avg_age_seconds": 12.5,

        "max_age_seconds": 45.3,

        "memory_estimate_kb": 26.0

        }'
      operationId: get_storage_stats_endpoint_v1_tools_stats_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Tools
  /v1/tools:
    get:
      summary: Agent Tools List
      description: 'List available tools in Agent API format (OAuth Required)


        CRITICAL FIX v1.30.23: OAuth protection now REQUIRED for /v1/tools


        Why: ChatGPT Agent was choosing Agent Actions API over MCP Protocol because

        /v1/tools was accessible without auth. By requiring OAuth here, ChatGPT is

        forced to use the MCP endpoint (/mcp) instead.


        Discovery flow:

        1. ChatGPT completes OAuth → gets token with mcp.endpoint

        2. ChatGPT scans /v1/tools → HTTP 401 (needs OAuth)

        3. ChatGPT falls back to /mcp → uses MCP Protocol ✅'
      operationId: agent_tools_list_v1_tools_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Tools
  /v1/tools/execute:
    get:
      summary: Agent Tools Execute
      description: 'Execute a tool via Agent API (Tool Endpoint - Auth Required)


        Supports both GET (with query parameters) and POST (with JSON body) requests

        Per ChatGPT feedback and Agent API best practices:

        - Tool execution requires Bearer token authentication

        - GET requests use query parameters: ?tool=search&arguments={"query":"test"}

        - POST requests use JSON body: {"tool": "search", "arguments": {"query": "test"}}'
      operationId: agent_tools_execute_v1_tools_execute_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Tools
    post:
      summary: Agent Tools Execute
      description: 'Execute a tool via Agent API (Tool Endpoint - Auth Required)


        Supports both GET (with query parameters) and POST (with JSON body) requests

        Per ChatGPT feedback and Agent API best practices:

        - Tool execution requires Bearer token authentication

        - GET requests use query parameters: ?tool=search&arguments={"query":"test"}

        - POST requests use JSON body: {"tool": "search", "arguments": {"query": "test"}}'
      operationId: agent_tools_execute_v1_tools_execute_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Tools
  /v1/tools/read_execute:
    post:
      summary: Agent Tools Execute Read
      description: Read-only execution endpoint (no side effects).
      operationId: agent_tools_execute_read_v1_tools_read_execute_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Tools
  /v1/tools/write_execute:
    post:
      summary: Agent Tools Execute Write
      description: Write execution endpoint (side effects allowed).
      operationId: agent_tools_execute_write_v1_tools_write_execute_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Tools
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ToolCallRequest:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
          description: Tool name to execute
        arguments:
          additionalProperties: true
          type: object
          title: Arguments
          description: Tool arguments
      type: object
      required:
      - name
      title: ToolCallRequest
      description: Request model for tool calls with strict validation
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError