mahastrategies-com Enterprise MCP Gateway API

openapi: 3.2.0
info:
  title: Maha Strategies MPS Enterprise MCP Gateway API
  version: '0.1'
  description: 'The Maha Provenance Standard (MPS) API runs claim-level provenance audits over prose. Every factual claim in a passage is excerpted, tagged (VERIFIED, SOURCED, BOUNDARY, ILLUSTRATIVE, UNVERIFIED), and returned with a rationale and a recommended action — so agents and editors can verify before they publish.


    ## Local bridge (CLI)


    Install the open-source local bridge and point Claude Code, Cursor, or any MCP client at it:


    ```sh

    npm install -g @mahastrategies/maha-mcp-bridge

    maha login # verify and store your credential

    maha serve # start the stdio MCP server

    ```


    Raw rows and credentials stay local; only locally-redacted context reaches the agent''s cloud model.


    ## Authentication


    Commercial endpoints use bearer credentials:


    ```

    Authorization: Bearer mhaic_your_credential_here

    ```


    Credentials are shown **exactly once** at purchase. Store them in a secret manager; never commit them, log them, or place them in URLs. Each credential is scoped to the MPS audit capability only — it cannot touch any other service. Lost credentials cannot be recovered, only replaced.


    The free preflight endpoint (`POST /api/audit`) needs no credential and is limited per visitor per day.


    ## The credit system


    Paid audits are prepaid. Each successful audit consumes one `mps_audit_invocation` credit; failed audits are refunded automatically in the same ledger.


    When a credential runs out of credits, the API responds with **`402 Payment Required`**:


    ```json

    {

    "error": { "code": "payment_required", "message": "This prepaid credential has no audit credits remaining." },

    "purchase": { "href": "/mps/audit-access", "checkoutEndpoint": "/api/mps-credits/checkout", "unit": "mps_audit_invocation" }

    }

    ```


    Treat `402` as a routine signal, not an error: follow `purchase.href` to buy another pack, or call the checkout endpoint programmatically. Balances live in an append-only double-entry ledger — every grant, consumption, refund, and manual correction is a permanent, hash-chained row.


    ## Idempotency and webhook resilience


    **Requests**: every audit takes a `clientRequestId` you choose (8–120 characters). Retrying with the same id and the same text returns the original result with `idempotentReplay: true` — never a duplicate charge. The same id with *different* text returns `409 Conflict`. Safe retry loop: keep the same id until you get a terminal status.


    **Payments**: Stripe webhooks are processed exactly once. Each event id is claimed atomically in the same database transaction that moves credits, so a redelivered webhook can never double-credit a balance — duplicates get `200 OK` with `"duplicate": true` and change nothing. A crash between claim and grant rolls both back together. You never need to reconcile double-grants; the ledger cannot express them.'
  contact:
    name: Maha Strategies
    url: https://www.mahastrategies.com/contact
servers:
- url: https://www.mahastrategies.com
tags:
- name: Enterprise MCP Gateway
  description: Tenant-scoped MCP proxy for operator-registered public upstream servers.
paths:
  /api/v1/mcp/register:
    post:
      tags:
      - Enterprise MCP Gateway
      summary: Register Upstream MCP Server
      description: Canonical gateway registration. Stores and encrypts upstream credentials, calls tools/list to persist a validated tool inventory, and applies an explicit method/tool policy. Encrypted credential material is never returned.
      security:
      - credential: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - baseUrl
              - authType
              - allowedMethods
              - allowedToolNames
              properties:
                name:
                  type: string
                baseUrl:
                  type: string
                authType:
                  type: string
                  enum:
                  - bearer
                  - hmac
                  - none
                secret:
                  type: string
                allowedMethods:
                  type: array
                  minItems: 1
                  uniqueItems: true
                  items:
                    type: string
                    enum:
                    - initialize
                    - notifications/initialized
                    - ping
                    - tools/list
                    - resources/list
                    - resources/read
                    - prompts/list
                    - prompts/get
                    - tools/call
                allowedToolNames:
                  type: array
                  maxItems: 256
                  uniqueItems: true
                  items:
                    type: string
                  description: tools/call requires at least one approved name. Names must come from the validated upstream inventory.
      responses:
        '201':
          description: Server registered successfully.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Missing required fields or invalid authType.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Internal failure registering MCP upstream server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      operationId: postApiV1McpRegister
      x-operation-id-source: derived
  /api/v1/mcp/servers:
    get:
      tags:
      - Enterprise MCP Gateway
      summary: List Registered MCP Servers
      description: Lists the authenticated API key’s registered MCP upstreams. Credentials and encrypted credential material are never returned.
      security:
      - credential: []
      responses:
        '200':
          description: Credential-safe MCP server summaries.
          content:
            application/json:
              schema:
                type: object
                required:
                - servers
                properties:
                  servers:
                    type: array
                    items:
                      type: object
                      required:
                      - serverId
                      - name
                      - baseUrl
                      - createdAt
                      - status
                      - policy
                      - discovery
                      properties:
                        serverId:
                          type: string
                        name:
                          type: string
                        baseUrl:
                          type: string
                          format: uri
                        createdAt:
                          type: integer
                        status:
                          type: string
                          enum:
                          - active
                          - suspended
                        policy:
                          type: object
                          required:
                          - allowedMethods
                          - allowedToolNames
                          - mode
                          properties:
                            allowedMethods:
                              type: array
                              items:
                                type: string
                            allowedToolNames:
                              type: array
                              items:
                                type: string
                            mode:
                              type: string
                              enum:
                              - explicit
                              - legacy_discovered
                        discovery:
                          type: object
                          required:
                          - status
                          - tools
                          properties:
                            status:
                              type: string
                              enum:
                              - pending
                              - ready
                              - error
                            discoveredAt:
                              type: integer
                            error:
                              type: string
                            tools:
                              type: array
                              items:
                                type: object
                                required:
                                - name
                                - inputSchema
                                properties:
                                  name:
                                    type: string
                                  description:
                                    type: string
                                  inputSchema:
                                    type: object
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: MCP registry unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      operationId: getApiV1McpServers
      x-operation-id-source: derived
  /api/v1/mcp/servers/{serverId}/discover:
    post:
      tags:
      - Enterprise MCP Gateway
      summary: Refresh MCP Tool Discovery
      description: Calls tools/list on a tenant-owned upstream, validates the bounded JSON-RPC response, and persists credential-safe tool metadata.
      security:
      - credential: []
      parameters:
      - name: serverId
        in: path
        required: true
        schema:
          type: string
          pattern: ^mcp_srv_[a-f0-9]{16}$
      responses:
        '200':
          description: Validated tool inventory persisted.
          content:
            application/json:
              schema:
                type: object
                required:
                - server
                properties:
                  server:
                    type: object
        '400':
          description: Invalid MCP server ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: MCP server not registered to this tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Tenant MCP request limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: Upstream discovery failed or returned invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Upstream circuit breaker open.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      operationId: postApiV1McpServersByServerIdDiscover
      x-operation-id-source: derived
  /api/v1/mcp/servers/{serverId}:
    patch:
      tags:
      - Enterprise MCP Gateway
      summary: Set MCP Server Method and Tool Policy
      description: Replaces the explicit policy for a tenant-owned upstream. Callable tool names must appear in the latest validated tools/list inventory.
      security:
      - credential: []
      parameters:
      - name: serverId
        in: path
        required: true
        schema:
          type: string
          pattern: ^mcp_srv_[a-f0-9]{16}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - allowedMethods
              - allowedToolNames
              properties:
                allowedMethods:
                  type: array
                  minItems: 1
                  uniqueItems: true
                  items:
                    type: string
                allowedToolNames:
                  type: array
                  maxItems: 256
                  uniqueItems: true
                  items:
                    type: string
                status:
                  type: string
                  enum:
                  - active
                  - suspended
      responses:
        '200':
          description: Updated credential-safe server summary.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid policy, status, or unknown tool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: MCP server not registered to this tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '415':
          description: Content-Type must be application/json.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: MCP registry unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      operationId: patchApiV1McpServersByServerId
      x-operation-id-source: derived
  /api/v1/mcp/settings:
    get:
      tags:
      - Enterprise MCP Gateway
      summary: Get Tenant MCP SLA Controls
      security:
      - credential: []
      responses:
        '200':
          description: Current tenant MCP controls.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: MCP controls unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      operationId: getApiV1McpSettings
      x-operation-id-source: derived
    post:
      tags:
      - Enterprise MCP Gateway
      summary: Set Tenant MCP SLA Controls
      security:
      - credential: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - requestsPerMinute
              - timeoutMs
              - failureThreshold
              - cooldownMs
              properties:
                requestsPerMinute:
                  type: integer
                  minimum: 1
                  maximum: 600
                timeoutMs:
                  type: integer
                  minimum: 1000
                  maximum: 30000
                failureThreshold:
                  type: integer
                  minimum: 1
                  maximum: 10
                cooldownMs:
                  type: integer
                  minimum: 5000
                  maximum: 300000
      responses:
        '200':
          description: Updated tenant MCP controls.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid MCP SLA controls.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '415':
          description: Content-Type must be application/json.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: MCP controls unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      operationId: postApiV1McpSettings
      x-operation-id-source: derived
  /api/v1/mcp/gateway/{serverId}:
    post:
      tags:
      - Enterprise MCP Gateway
      summary: Proxy JSON-RPC call to Upstream MCP Server (v1)
      description: Proxies, signs, and audits tool calls made by enterprise AI agents via the v1 App Router endpoint. The upstream server must belong to the authenticated API key.
      security:
      - credential: []
      parameters:
      - name: serverId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - jsonrpc
              - method
              properties:
                jsonrpc:
                  const: '2.0'
                id:
                  oneOf:
                  - type: string
                  - type: number
                method:
                  type: string
                params:
                  type: object
      responses:
        '200':
          description: JSON-RPC 2.0 Response from upstream.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid JSON-RPC 2.0 payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: MCP method or tool is not permitted by the server policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Target MCP Server not registered for this tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '413':
          description: MCP request exceeds 64 KB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Tenant MCP request limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Internal MCP Gateway Processing Failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '502':
          description: Upstream MCP server returned an error or invalid response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Upstream circuit breaker open or server suspended.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '504':
          description: Upstream MCP timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      operationId: postApiV1McpGatewayByServerId
      x-operation-id-source: derived
components:
  schemas:
    ErrorEnvelope:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
            message:
              type: string
              description: Human-readable explanation.
  securitySchemes:
    credential:
      type: http
      scheme: bearer
      description: MPS client credential (`mhaic_…`), issued once at purchase.