openapi: 3.0.3
info:
  title: TATER MCP HTTP Endpoint
  description: |
    Model Context Protocol (MCP) HTTP endpoint for TATER. Exposes 42 compliance, risk, change control,
    config documentation, and evidence tools as JSON-RPC 2.0 over HTTP. Used by Microsoft 365 Copilot,
    Copilot Studio, and any other MCP-aware client.

    Auth: pass an Entra ID OAuth token in the `Authorization: Bearer` header (audience
    `api://45afb90d-c5de-439d-8b09-8fbfed28b321`), OR a TATER API key via `?api_key=&org_id=` query
    parameters or `x-api-key` header. The first MCP `tools/call` of every session MUST be
    `get_org_context` to confirm which TATER organization is active.

    All actions are recorded in TATER's audit log with `metadata.via='copilot'` when the request
    originates from a Copilot user-agent.
  version: "1.0.0"
  contact:
    name: TATER Security
    email: support@tatersecurity.com
    url: https://www.tatersecurity.com
servers:
  - url: https://api.tatersecurity.com
    description: Production
paths:
  /api/mcp:
    post:
      operationId: mcp_invoke
      summary: Invoke any TATER MCP tool via JSON-RPC 2.0
      description: |
        Standard MCP server endpoint. Send a JSON-RPC 2.0 request with method=`tools/list` (no params)
        to discover tools, or method=`tools/call` with `params={name, arguments}` to invoke one.

        The first call of every conversation should be:
          `tools/call` with `{name: "get_org_context", arguments: {}}`
        to confirm the active organization.
      security:
        - tater_oauth: []
      x-ms-visibility: important
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [jsonrpc, method]
              properties:
                jsonrpc:
                  type: string
                  enum: ["2.0"]
                id:
                  oneOf:
                    - type: string
                    - type: integer
                method:
                  type: string
                  enum: ["tools/list", "tools/call", "ping"]
                params:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Tool name (required for tools/call)
                    arguments:
                      type: object
                      description: Tool-specific arguments (required for tools/call)
      responses:
        "200":
          description: JSON-RPC 2.0 response (success or error envelope)
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    type: string
                  id:
                    oneOf:
                      - type: string
                      - type: integer
                      - type: "null"
                  result:
                    type: object
                  error:
                    type: object
                    properties:
                      code: { type: integer }
                      message: { type: string }
        "401":
          description: Unauthorized — missing or invalid token
        "429":
          description: Rate limit exceeded
components:
  securitySchemes:
    tater_oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            api://45afb90d-c5de-439d-8b09-8fbfed28b321/access: Access TATER on behalf of the signed-in user
