{"openapi":"3.1.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"}],"externalDocs":{"description":"byImprint Developer Resources","url":"https://byimprint.com/developers"},"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":"MCP-Protocol-Version","in":"header","required":false,"description":"Current protocol version. Use 2026-07-28 for server/discover and modern tool calls; 2025-11-25 remains available for initialize compatibility.","schema":{"type":"string","enum":["2026-07-28","2025-11-25"]}},{"name":"Mcp-Method","in":"header","required":false,"description":"The JSON-RPC method name, repeated as a header for current Streamable HTTP routing.","schema":{"type":"string","enum":["server/discover","initialize","tools/list","tools/call"]}},{"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"]}}],"requestBody":{"required":true,"description":"A JSON-RPC 2.0 MCP request. Current MCP clients should include MCP-Protocol-Version, Mcp-Method, and Mcp-Name headers as applicable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"},"examples":{"discover":{"summary":"Discover the current MCP protocol","value":{"jsonrpc":"2.0","id":"discover-1","method":"server/discover","params":{}}},"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","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"}]},"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},"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},"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},"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}}},"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}}]}