{ "openapi": "3.1.0", "info": { "title": "Carna MCP Gateway", "version": "1.0.0", "description": "Carna's public Model Context Protocol gateway. Read-only marketing tools served locally; AI tools proxied to the cfs-api backend. Spec: https://modelcontextprotocol.io" }, "servers": [ { "url": "https://carna.ai/api/mcp", "description": "Production" }, { "url": "https://carna.ai/api/mcp", "description": "Origin (path-based)" } ], "paths": { "/tools/get_pricing": { "post": { "operationId": "get_pricing", "summary": "Return pricing tiers for a Carna product family", "description": "Return pricing tiers for a Carna product family. Region is informational; v1 returns the same tiers per product.", "tags": [ "static" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "enum": [ "individuals", "schools", "business" ], "description": "Carna product family" }, "region": { "type": "string", "enum": [ "EU", "TR", "US" ], "description": "Pricing region (optional)" } }, "required": [ "product" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string" }, "region": { "type": "string" }, "currency": { "type": "string" }, "tiers": { "type": "object" }, "notes": { "type": "object" }, "docsUrl": { "type": "string" } } } } } }, "400": { "description": "Invalid params (-32602)" }, "500": { "description": "Internal error (-32603)" } } } }, "/tools/list_voices": { "post": { "operationId": "list_voices", "summary": "Describe how Carna uses speech: listening dialogues are voiced so that each speaker sounds different", "description": "Describe how Carna uses speech: listening dialogues are voiced so that each speaker sounds different. There is no voice picker, no named tutor cast, and no voice count to quote.", "tags": [ "static" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" }, "isError": { "type": "object" } }, "description": "MCP tool result envelope." } } } }, "400": { "description": "Invalid params (-32602)" }, "500": { "description": "Internal error (-32603)" } } } }, "/tools/get_company_facts": { "post": { "operationId": "get_company_facts", "summary": "Return Carna company facts (legal entity, address, social) and high-level brand stats", "description": "Return Carna company facts (legal entity, address, social) and high-level brand stats. Locale-aware via Q6 brand decision.", "tags": [ "static" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "en", "tr" ], "description": "Pick legal entity by locale (Q6)" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" }, "isError": { "type": "object" } }, "description": "MCP tool result envelope." } } } }, "400": { "description": "Invalid params (-32602)" }, "500": { "description": "Internal error (-32603)" } } } }, "/tools/compare_with_competitor": { "post": { "operationId": "compare_with_competitor", "summary": "Return a structured Carna-vs-competitor comparison skeleton", "description": "Return a structured Carna-vs-competitor comparison skeleton. Real CMS-driven content comes later; v1 returns links + known-competitor stub.", "tags": [ "static" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "competitor": { "type": "string", "description": "Competitor slug or display name" }, "product": { "type": "string", "enum": [ "individuals", "schools", "business" ] } }, "required": [ "competitor" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" }, "isError": { "type": "object" } }, "description": "MCP tool result envelope." } } } }, "400": { "description": "Invalid params (-32602)" }, "500": { "description": "Internal error (-32603)" } } } }, "/tools/find_use_case": { "post": { "operationId": "find_use_case", "summary": "Route a (persona, goal) pair to the most relevant Carna page", "description": "Route a (persona, goal) pair to the most relevant Carna page. Hard-coded routing table; for AI-driven recommendations call recommend_use_case.", "tags": [ "static" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "persona": { "type": "string", "enum": [ "individual", "teacher", "school-admin", "hr", "sales-leader", "ielts-candidate", "kid-parent" ] }, "goal": { "type": "string", "description": "Free-text learner goal" } }, "required": [ "persona", "goal" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" }, "isError": { "type": "object" } }, "description": "MCP tool result envelope." } } } }, "400": { "description": "Invalid params (-32602)" }, "500": { "description": "Internal error (-32603)" } } } }, "/tools/list_products": { "post": { "operationId": "list_products", "summary": "List Carna's product family — three in-domain products plus the Carna Test cross-domain sub-brand", "description": "List Carna's product family — three in-domain products plus the Carna Test cross-domain sub-brand.", "tags": [ "static" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" }, "isError": { "type": "object" } }, "description": "MCP tool result envelope." } } } }, "400": { "description": "Invalid params (-32602)" }, "500": { "description": "Internal error (-32603)" } } } }, "/tools/describe_brand": { "post": { "operationId": "describe_brand", "summary": "Short EN brand description block", "description": "Short EN brand description block. The master line is \"the AI English tutor that knows you\" (founder, 27 Sep 2026); Carna for Schools and Carna for Business are the same engine for organisations.", "tags": [ "static" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" }, "isError": { "type": "object" } }, "description": "MCP tool result envelope." } } } }, "400": { "description": "Invalid params (-32602)" }, "500": { "description": "Internal error (-32603)" } } } }, "/tools/request_demo": { "post": { "operationId": "request_demo", "summary": "Submit a B2B demo or partnership request", "description": "Submit a B2B demo or partnership request. Routes to the matching Slack pipeline (school-partnership / corporate-partnership / test-enterprise) and persists to LEAD_STORE for 90 days.", "tags": [ "static" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant": { "type": "string", "enum": [ "demo", "school-partnership", "corporate-partnership", "test-enterprise" ], "description": "Lead variant routes to the matching Slack webhook." }, "name": { "type": "string" }, "email": { "type": "string", "description": "Work email" }, "role": { "type": "string", "description": "e.g. Head of L&D, K-12 Principal, IT Director" }, "organization": { "type": "string", "description": "Organization or school name" }, "country": { "type": "string", "description": "ISO-3166 alpha-2 (TR, GB, US, ...)" }, "studentCount": { "type": "number", "description": "Approximate learner headcount (optional)" }, "message": { "type": "string", "description": "Free-text intro (optional)" }, "cfTurnstileToken": { "type": "string", "description": "Cloudflare Turnstile token (optional in v1; gateway is rate-limited and behind WAF)" } }, "required": [ "variant", "name", "email", "role", "organization", "country" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "leadId": { "type": "string" }, "expectedResponseTime": { "type": "string" } } } } } }, "400": { "description": "Invalid params (-32602)" }, "500": { "description": "Internal error (-32603)" } } } }, "/tools/assess_english_level": { "post": { "operationId": "assess_english_level", "summary": "Estimate the learner's CEFR level + 4-rubric breakdown from a writing sample or speaking audio", "description": "Estimate the learner's CEFR level + 4-rubric breakdown from a writing sample or speaking audio. Calls the cfs-api AI engine.", "tags": [ "ai" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Sample of the learner's writing" }, "audio_url": { "type": "string", "description": "Public URL to learner audio sample" }, "locale": { "type": "string", "description": "BCP-47 locale (e.g. en, tr)" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" }, "isError": { "type": "object" } }, "description": "MCP tool result envelope." } } } }, "400": { "description": "Invalid params (-32602)" }, "500": { "description": "Internal error (-32603)" } } } }, "/tools/recommend_use_case": { "post": { "operationId": "recommend_use_case", "summary": "AI-driven Carna page + curriculum recommendation", "description": "AI-driven Carna page + curriculum recommendation. More sophisticated than `find_use_case` (which uses a hard-coded routing table).", "tags": [ "ai" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "persona": { "type": "string", "enum": [ "individual", "teacher", "school-admin", "hr", "sales-leader", "ielts-candidate", "kid-parent" ] }, "goal": { "type": "string" }, "current_level": { "type": "string", "description": "CEFR level if known" } }, "required": [ "persona", "goal" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" }, "isError": { "type": "object" } }, "description": "MCP tool result envelope." } } } }, "400": { "description": "Invalid params (-32602)" }, "500": { "description": "Internal error (-32603)" } } } }, "/tools/check_school_fit": { "post": { "operationId": "check_school_fit", "summary": "Compute a Carna-for-Schools fit score and recommended plan based on institution profile", "description": "Compute a Carna-for-Schools fit score and recommended plan based on institution profile.", "tags": [ "ai" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO-3166 alpha-2 (e.g. TR, GB, US)" }, "institution_type": { "type": "string", "enum": [ "k12-public", "k12-private", "university", "language-school", "test-prep-center", "corporate" ] }, "student_count": { "type": "number", "description": "Approximate student headcount" }, "languages_taught": { "type": "array", "description": "ISO-639 codes of languages currently taught" } }, "required": [ "country", "institution_type", "student_count" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "object" }, "isError": { "type": "object" } }, "description": "MCP tool result envelope." } } } }, "400": { "description": "Invalid params (-32602)" }, "500": { "description": "Internal error (-32603)" } } } } } }