byImprint MCP API

openapi: 3.2.0
info:
  title: byImprint MCP API
  version: 1.1.0
  description: Typed protocol schema for byImprint's public, read-only Streamable HTTP MCP endpoint. MCP is the only current callable interface; this document does not advertise a separate REST product.
  contact:
    name: James Hutchings
    email: james@byimprint.com
    url: https://byimprint.com/developers
  x-versioning-policy: https://byimprint.com/developers/versioning
servers:
- url: https://byimprint.com
tags:
- name: MCP
paths:
  /.well-known/mcp:
    post:
      operationId: callByImprintMcp
      summary: Call the public byImprint MCP server
      description: Send a JSON-RPC request to the public, read-only byImprint MCP endpoint. Use server/discover to negotiate the current protocol, tools/list to inspect strict tool schemas, and tools/call to retrieve public guidance. The server cannot send messages, change accounts, spend money, create commitments, or access client data.
      tags:
      - MCP
      x-rate-limit-policy:
        name: byimprint-public-mcp
        requests: 60
        windowSeconds: 60
      security: []
      parameters:
      - name: Accept
        in: header
        required: true
        description: Must include both application/json and text/event-stream. The server returns 406 Not Acceptable otherwise.
        schema:
          type: string
        example: application/json, text/event-stream
      - name: Content-Type
        in: header
        required: true
        description: Must be application/json. The server returns 415 Unsupported Media Type otherwise.
        schema:
          type: string
        example: application/json
      - name: MCP-Protocol-Version
        in: header
        required: false
        description: Current protocol version. Sending this header switches the request into the 2026-07-28 dialect, which then also requires the Mcp-Method header and a params._meta envelope naming the same version on every call, not only server/discover; omit it entirely for the initialize compatibility handshake, tools/list, and tools/call. Use 2026-07-28 for server/discover; 2025-11-25 remains available for initialize compatibility.
        schema:
          type: string
          enum:
          - '2026-07-28'
          - '2025-11-25'
        examples:
          discover:
            value: '2026-07-28'
      - name: Mcp-Method
        in: header
        required: false
        description: The JSON-RPC method name, repeated as a header for current Streamable HTTP routing. Required whenever MCP-Protocol-Version is sent, including server/discover, whose handler rejects a request that omits it (a body naming server/discover with no matching Mcp-Method header is a 400 header/body mismatch); omit it entirely for initialize, tools/list, and tools/call.
        schema:
          type: string
          enum:
          - server/discover
          - initialize
          - tools/list
          - tools/call
        examples:
          discover:
            value: server/discover
      - name: Mcp-Name
        in: header
        required: false
        description: The MCP tool name when Mcp-Method is tools/call.
        schema:
          type: string
          enum:
          - byimprint-when-to-use
          - byimprint-site-index
        examples:
          callTool:
            value: byimprint-when-to-use
      requestBody:
        required: true
        description: A JSON-RPC 2.0 MCP request, sent with the Accept and Content-Type headers above. server/discover additionally requires the MCP-Protocol-Version and Mcp-Method headers and a matching params._meta envelope, shown in the discover example; tools/list and tools/call do not, and should omit MCP-Protocol-Version and Mcp-Method rather than send them without a matching params._meta.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
            examples:
              discover:
                summary: Discover the current MCP protocol
                description: 'Send with header MCP-Protocol-Version: 2026-07-28 and header Mcp-Method: server/discover; both are required for this method.'
                value:
                  jsonrpc: '2.0'
                  id: discover-1
                  method: server/discover
                  params:
                    _meta:
                      io.modelcontextprotocol/protocolVersion: '2026-07-28'
                      io.modelcontextprotocol/clientInfo:
                        name: byimprint-openapi-example
                        version: 1.0.0
                      io.modelcontextprotocol/clientCapabilities: {}
              listTools:
                summary: List the read-only tools
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: tools/list
                  params: {}
              callTool:
                summary: Call a read-only guidance tool
                description: 'Send with header Mcp-Name: byimprint-when-to-use.'
                value:
                  jsonrpc: '2.0'
                  id: 2
                  method: tools/call
                  params:
                    name: byimprint-when-to-use
                    arguments: {}
      responses:
        '200':
          description: A complete MCP result or a JSON-RPC protocol error.
          headers:
            RateLimit-Policy:
              description: The structured public quota policy.
              schema:
                type: string
            RateLimit:
              description: The structured quota remaining and reset window.
              schema:
                type: string
            X-RateLimit-Limit:
              description: The public request limit per quota window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current quota window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp when the current quota window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/JsonRpcSuccessResponse'
                - $ref: '#/components/schemas/JsonRpcErrorResponse'
            text/event-stream:
              schema:
                type: string
        '400':
          description: Malformed JSON or an invalid JSON-RPC request. The error data includes a stable code and a recovery hint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
        '403':
          description: Host or Origin validation failed. Retry against the canonical HTTPS endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
        '405':
          description: The endpoint accepts POST and OPTIONS, not GET.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
        '406':
          description: The requested representation is unsupported. Accept application/json and text/event-stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
        '429':
          description: The public per-IP request quota is exhausted. Wait for Retry-After, then retry the same request.
          headers:
            RateLimit-Policy:
              description: The structured public quota policy.
              schema:
                type: string
            RateLimit:
              description: The structured quota remaining and reset window.
              schema:
                type: string
            Retry-After:
              description: Seconds before the client should retry.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcErrorResponse'
components:
  schemas:
    JsonRpcId:
      oneOf:
      - type: string
      - type: integer
    JsonRpcSuccessResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          $ref: '#/components/schemas/JsonRpcId'
        result:
          type: object
          additionalProperties: true
      required:
      - jsonrpc
      - id
      - result
      additionalProperties: false
    JsonRpcRequest:
      type: object
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          $ref: '#/components/schemas/JsonRpcId'
        method:
          type: string
          enum:
          - server/discover
          - initialize
          - tools/list
          - tools/call
        params:
          type: object
          description: Method-specific MCP parameters. Tool input schemas are published by tools/list and repeated in x-mcp-tools.
          additionalProperties: true
      required:
      - jsonrpc
      - id
      - method
      additionalProperties: false
    JsonRpcErrorResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
          - $ref: '#/components/schemas/JsonRpcId'
          - type: 'null'
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            data:
              $ref: '#/components/schemas/JsonRpcErrorData'
          required:
          - code
          - message
          - data
          additionalProperties: false
      required:
      - jsonrpc
      - id
      - error
      additionalProperties: false
    JsonRpcErrorData:
      type: object
      properties:
        errorCode:
          type: string
          description: Stable machine-readable byImprint error identifier.
        resolutionHint:
          type: string
          description: A concrete next step an agent can use to recover.
      required:
      - errorCode
      - resolutionHint
      additionalProperties: false
externalDocs:
  description: byImprint Developer Resources
  url: https://byimprint.com/developers
x-mcp-tools:
- name: byimprint-when-to-use
  title: When to use byImprint
  description: Return current, bounded guidance for deciding when byImprint fits an owner-led business.
  inputSchema:
    type: object
    properties: {}
    additionalProperties: false
  outputSchema:
    type: object
    properties:
      markdown:
        type: string
        description: Current public byImprint guidance in Markdown.
    required:
    - markdown
    additionalProperties: false
  annotations:
    readOnlyHint: true
    destructiveHint: false
    idempotentHint: true
    openWorldHint: false
- name: byimprint-site-index
  title: byImprint public site index
  description: Return canonical public service, evidence, legal, developer, and machine-readable URLs for byImprint.
  inputSchema:
    type: object
    properties: {}
    additionalProperties: false
  outputSchema:
    type: object
    properties:
      markdown:
        type: string
        description: Current public byImprint guidance in Markdown.
    required:
    - markdown
    additionalProperties: false
  annotations:
    readOnlyHint: true
    destructiveHint: false
    idempotentHint: true
    openWorldHint: false