{
  "openapi": "3.1.1",
  "info": {
    "title": "Flowlines MCP transport",
    "version": "1.0.0",
    "description": "The public Streamable HTTP MCP transport, not the internal Flowlines REST API. Prefer a native MCP client. Read live OAuth metadata, sign in with user consent and PKCE S256, initialize, then use tools/list for current tool schemas. Tool availability and access depend on the authenticated workspace. The email scope is an identity scope, not a per-tool read/write permission."
  },
  "servers": [{ "url": "https://api.flowlines.ai" }],
  "externalDocs": { "url": "https://flowlines.ai/docs#agent-connection", "description": "Connection, permissions and guided onboarding" },
  "paths": {
    "/mcp": {
      "post": {
        "operationId": "sendMcpMessage",
        "summary": "Send a JSON-RPC message to the Flowlines MCP server",
        "description": "Use the MCP lifecycle: initialize, notifications/initialized, then tools/list and supported tool calls. Supply Accept: application/json, text/event-stream as required by Streamable HTTP. Include the negotiated MCP-Protocol-Version on subsequent requests and any MCP-Session-Id issued by the server. Do not send JSON-RPC batches. This operation requires a Flowlines OAuth access token; a telemetry namespace API key is not a substitute.",
        "security": [{ "flowlinesOAuth": ["email"] }],
        "parameters": [
          { "name": "MCP-Protocol-Version", "in": "header", "description": "Negotiated MCP protocol version on requests after initialization.", "schema": { "type": "string" } },
          { "name": "MCP-Session-Id", "in": "header", "description": "Include only if the server issued a session identifier.", "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/JsonRpcMessage" },
              "examples": {
                "initialize": { "value": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": { "name": "your-mcp-client", "version": "1.0.0" } } } },
                "initialized": { "value": { "jsonrpc": "2.0", "method": "notifications/initialized" } },
                "listTools": { "value": { "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} } }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A JSON-RPC response or a server-sent event stream. Protocol-level errors can also arrive in a successful HTTP response.",
            "headers": { "MCP-Session-Id": { "description": "Session identifier, when issued by the server.", "schema": { "type": "string" } } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } },
              "text/event-stream": { "schema": { "type": "string" } }
            }
          },
          "202": { "description": "Notification accepted; no response body." },
          "400": { "description": "Invalid request, session or protocol version." },
          "401": { "description": "Missing or invalid OAuth access token. Discover authorization through /.well-known/oauth-protected-resource/mcp on this API origin and sign in." },
          "403": { "description": "Request origin or authenticated operation is not allowed." },
          "406": { "description": "Client must accept both application/json and text/event-stream." },
          "413": { "description": "Request body is too large." }
        }
      }
    },
    "/.well-known/oauth-protected-resource/mcp": {
      "get": {
        "operationId": "getMcpProtectedResourceMetadata",
        "summary": "Discover the MCP resource, authorization server and supported scopes",
        "security": [],
        "responses": { "200": { "description": "RFC 9728 protected-resource metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProtectedResourceMetadata" } } } } }
      }
    },
    "/.well-known/oauth-authorization-server": {
      "get": {
        "operationId": "getMcpAuthorizationServerMetadata",
        "summary": "Discover live OAuth endpoints and PKCE support",
        "security": [],
        "responses": { "200": { "description": "RFC 8414 authorization-server metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationServerMetadata" } } } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "flowlinesOAuth": {
        "type": "oauth2",
        "description": "Authorization code flow with user sign-in and PKCE S256. Refresh the endpoint URLs from live RFC 8414 metadata before authorization. email is the currently declared identity scope; no independent read/write tool scopes are claimed.",
        "flows": { "authorizationCode": {
          "authorizationUrl": "https://auth.flowlines.ai/auth/v1/oauth/authorize",
          "tokenUrl": "https://api.flowlines.ai/mcp/oauth/token",
          "scopes": { "email": "Email identity scope advertised by the Flowlines authorization server. Not a per-tool permission." }
        } }
      }
    },
    "schemas": {
      "JsonRpcMessage": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "const": "2.0" },
          "id": { "type": ["string", "integer"], "description": "Required for requests; omit for notifications." },
          "method": { "type": "string", "minLength": 1 },
          "params": { "type": "object", "additionalProperties": true }
        },
        "additionalProperties": false
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc", "id"],
        "properties": {
          "jsonrpc": { "const": "2.0" },
          "id": { "type": ["string", "integer", "null"] },
          "result": { "type": "object", "additionalProperties": true },
          "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": {} } }
        },
        "oneOf": [{ "required": ["result"], "not": { "required": ["error"] } }, { "required": ["error"], "not": { "required": ["result"] } }]
      },
      "ProtectedResourceMetadata": {
        "type": "object",
        "required": ["resource", "authorization_servers"],
        "properties": {
          "resource": { "type": "string", "format": "uri" },
          "resource_name": { "type": "string" },
          "authorization_servers": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uri" } },
          "scopes_supported": { "type": "array", "items": { "type": "string" } },
          "bearer_methods_supported": { "type": "array", "items": { "type": "string" } }
        }
      },
      "AuthorizationServerMetadata": {
        "type": "object",
        "required": ["issuer", "authorization_endpoint", "token_endpoint", "response_types_supported"],
        "properties": {
          "issuer": { "type": "string", "format": "uri" },
          "authorization_endpoint": { "type": "string", "format": "uri" },
          "token_endpoint": { "type": "string", "format": "uri" },
          "registration_endpoint": { "type": "string", "format": "uri" },
          "scopes_supported": { "type": "array", "items": { "type": "string" } },
          "response_types_supported": { "type": "array", "items": { "type": "string" } },
          "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  }
}