first commit
This commit is contained in:
Beyhan Oğur
446
docs/openapi/schemas/management/mcp.yaml
Normal file
446
docs/openapi/schemas/management/mcp.yaml
Normal file
@@ -0,0 +1,446 @@
|
||||
# MCP API schemas
|
||||
|
||||
MCPAuthType:
|
||||
type: string
|
||||
enum: [none, headers, oauth, per_user_oauth]
|
||||
description: |
|
||||
Authentication type for MCP connections:
|
||||
- none: No authentication
|
||||
- headers: Header-based authentication (API keys, custom headers, etc.)
|
||||
- oauth: OAuth 2.0 authentication (server-level, admin authenticates once)
|
||||
- per_user_oauth: Per-user OAuth 2.0 authentication (each user authenticates individually)
|
||||
|
||||
MCPConnectionType:
|
||||
type: string
|
||||
enum: [http, stdio, sse, inprocess]
|
||||
description: Connection type for MCP client
|
||||
|
||||
MCPConnectionState:
|
||||
type: string
|
||||
enum: [connected, disconnected, error]
|
||||
description: Connection state of an MCP client
|
||||
|
||||
MCPStdioConfig:
|
||||
type: object
|
||||
description: STDIO configuration for MCP client
|
||||
properties:
|
||||
command:
|
||||
type: string
|
||||
description: Executable command to run
|
||||
args:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Command line arguments
|
||||
envs:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Environment variables required
|
||||
|
||||
MCPClientCreateRequest:
|
||||
oneOf:
|
||||
- $ref: '#/MCPClientCreateRequestHTTP'
|
||||
- $ref: '#/MCPClientCreateRequestSSE'
|
||||
- $ref: '#/MCPClientCreateRequestSTDIO'
|
||||
discriminator:
|
||||
propertyName: connection_type
|
||||
mapping:
|
||||
http: '#/MCPClientCreateRequestHTTP'
|
||||
sse: '#/MCPClientCreateRequestSSE'
|
||||
stdio: '#/MCPClientCreateRequestSTDIO'
|
||||
description: |
|
||||
MCP client configuration for creating a new client (tool_pricing not available at creation).
|
||||
The schema varies based on connection_type:
|
||||
- HTTP/SSE: connection_string is required
|
||||
- STDIO: stdio_config is required
|
||||
- InProcess: server instance must be provided programmatically (Go package only)
|
||||
|
||||
MCPClientCreateRequestBase:
|
||||
type: object
|
||||
required:
|
||||
- name
|
||||
- connection_type
|
||||
properties:
|
||||
client_id:
|
||||
type: string
|
||||
description: Unique identifier for the MCP client (optional, auto-generated if not provided)
|
||||
name:
|
||||
type: string
|
||||
description: Display name for the MCP client
|
||||
is_code_mode_client:
|
||||
type: boolean
|
||||
|
||||
is_ping_available:
|
||||
type: boolean
|
||||
default: true
|
||||
description: |
|
||||
Whether the MCP server supports ping for health checks.
|
||||
If true, uses lightweight ping method for health checks.
|
||||
If false, uses listTools method for health checks instead.
|
||||
connection_type:
|
||||
$ref: '#/MCPConnectionType'
|
||||
auth_type:
|
||||
$ref: '#/MCPAuthType'
|
||||
description: Authentication type for the MCP connection
|
||||
oauth_config_id:
|
||||
type: string
|
||||
description: |
|
||||
OAuth config ID for OAuth authentication.
|
||||
Set after OAuth flow is completed. References the oauth_configs table.
|
||||
Only relevant when auth_type is "oauth".
|
||||
headers:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
description: |
|
||||
Custom headers to include in requests.
|
||||
Only used when auth_type is "headers".
|
||||
oauth_config:
|
||||
$ref: '../../schemas/management/oauth.yaml#/OAuthConfigRequest'
|
||||
description: |
|
||||
OAuth configuration for initiating OAuth flow.
|
||||
Only include this when creating a client with auth_type "oauth".
|
||||
This will trigger the OAuth flow and return an authorization URL.
|
||||
tools_to_execute:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |
|
||||
Include-only list for tools.
|
||||
["*"] => all tools are included
|
||||
[] => no tools are included
|
||||
["tool1", "tool2"] => include only the specified tools
|
||||
tools_to_auto_execute:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |
|
||||
List of tools that can be auto-executed without user approval.
|
||||
Must be a subset of tools_to_execute.
|
||||
["*"] => all executable tools can be auto-executed
|
||||
[] => no tools are auto-executed
|
||||
["tool1", "tool2"] => only specified tools can be auto-executed
|
||||
allow_on_all_virtual_keys:
|
||||
type: boolean
|
||||
default: false
|
||||
description: |
|
||||
When true, this MCP client's tools are available to all virtual keys by default,
|
||||
without requiring an explicit virtual key assignment.
|
||||
An explicit virtual key config always overrides this setting for that key.
|
||||
MCPClientCreateRequestHTTP:
|
||||
allOf:
|
||||
- $ref: '#/MCPClientCreateRequestBase'
|
||||
- type: object
|
||||
required:
|
||||
- connection_string
|
||||
properties:
|
||||
connection_type:
|
||||
type: string
|
||||
enum: [http]
|
||||
connection_string:
|
||||
type: string
|
||||
description: HTTP URL (required for HTTP connection type)
|
||||
|
||||
MCPClientCreateRequestSSE:
|
||||
allOf:
|
||||
- $ref: '#/MCPClientCreateRequestBase'
|
||||
- type: object
|
||||
required:
|
||||
- connection_string
|
||||
properties:
|
||||
connection_type:
|
||||
type: string
|
||||
enum: [sse]
|
||||
connection_string:
|
||||
type: string
|
||||
description: SSE URL (required for SSE connection type)
|
||||
|
||||
MCPClientCreateRequestSTDIO:
|
||||
allOf:
|
||||
- $ref: '#/MCPClientCreateRequestBase'
|
||||
- type: object
|
||||
required:
|
||||
- stdio_config
|
||||
properties:
|
||||
connection_type:
|
||||
type: string
|
||||
enum: [stdio]
|
||||
stdio_config:
|
||||
$ref: '#/MCPStdioConfig'
|
||||
description: STDIO configuration (required for STDIO connection type)
|
||||
|
||||
MCPClientUpdateRequest:
|
||||
type: object
|
||||
description: MCP client configuration for updating an existing client (includes tool_pricing)
|
||||
properties:
|
||||
client_id:
|
||||
type: string
|
||||
description: Unique identifier for the MCP client
|
||||
name:
|
||||
type: string
|
||||
description: Display name for the MCP client
|
||||
is_code_mode_client:
|
||||
type: boolean
|
||||
description: Whether this client is available in code mode
|
||||
connection_type:
|
||||
$ref: '#/MCPConnectionType'
|
||||
connection_string:
|
||||
type: string
|
||||
description: HTTP or SSE URL (required for HTTP or SSE connections)
|
||||
stdio_config:
|
||||
$ref: '#/MCPStdioConfig'
|
||||
auth_type:
|
||||
$ref: '#/MCPAuthType'
|
||||
description: Authentication type for the MCP connection
|
||||
oauth_config_id:
|
||||
type: string
|
||||
description: |
|
||||
OAuth config ID for OAuth authentication.
|
||||
References the oauth_configs table.
|
||||
Only relevant when auth_type is "oauth".
|
||||
headers:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
description: |
|
||||
Custom headers to include in requests.
|
||||
Only used when auth_type is "headers".
|
||||
tools_to_execute:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |
|
||||
Include-only list for tools.
|
||||
["*"] => all tools are included
|
||||
[] => no tools are included
|
||||
["tool1", "tool2"] => include only the specified tools
|
||||
tools_to_auto_execute:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |
|
||||
List of tools that can be auto-executed without user approval.
|
||||
Must be a subset of tools_to_execute.
|
||||
["*"] => all executable tools can be auto-executed
|
||||
[] => no tools are auto-executed
|
||||
["tool1", "tool2"] => only specified tools can be auto-executed
|
||||
tool_pricing:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: number
|
||||
format: double
|
||||
description: |
|
||||
Per-tool cost in USD for execution.
|
||||
Key is the tool name, value is the cost per execution.
|
||||
Example: {"read_file": 0.001, "write_file": 0.002}
|
||||
Note: Only available when updating an existing client after tools have been fetched.
|
||||
allow_on_all_virtual_keys:
|
||||
type: boolean
|
||||
default: false
|
||||
description: |
|
||||
When true, this MCP client's tools are accessible to all virtual keys without requiring
|
||||
explicit per-key assignment. All tools are allowed by default. If a virtual key has an
|
||||
explicit MCP config for this client, that config takes precedence and overrides this behaviour.
|
||||
vk_configs:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/MCPVKConfig'
|
||||
description: |
|
||||
When provided, replaces all virtual key assignments for this MCP client.
|
||||
Each entry specifies a virtual key and the tools it is allowed to call.
|
||||
To remove all VK access, provide an empty array [].
|
||||
Omit this field to leave existing VK assignments unchanged.
|
||||
|
||||
MCPVKConfig:
|
||||
type: object
|
||||
description: Per-virtual-key tool access configuration for an MCP client
|
||||
required:
|
||||
- virtual_key_id
|
||||
- tools_to_execute
|
||||
properties:
|
||||
virtual_key_id:
|
||||
type: string
|
||||
description: ID of the virtual key
|
||||
tools_to_execute:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |
|
||||
Tools this virtual key is allowed to call on this MCP server.
|
||||
["*"] => all tools allowed
|
||||
["tool1", "tool2"] => only the specified tools
|
||||
|
||||
MCPClientConfig:
|
||||
type: object
|
||||
description: Full MCP client configuration (used in responses)
|
||||
properties:
|
||||
client_id:
|
||||
type: string
|
||||
description: Unique identifier for the MCP client
|
||||
name:
|
||||
type: string
|
||||
description: Display name for the MCP client
|
||||
is_code_mode_client:
|
||||
type: boolean
|
||||
description: Whether this client is available in code mode
|
||||
connection_type:
|
||||
$ref: '#/MCPConnectionType'
|
||||
connection_string:
|
||||
type: string
|
||||
description: HTTP or SSE URL (required for HTTP or SSE connections)
|
||||
stdio_config:
|
||||
$ref: '#/MCPStdioConfig'
|
||||
auth_type:
|
||||
$ref: '#/MCPAuthType'
|
||||
description: Authentication type for the MCP connection
|
||||
oauth_config_id:
|
||||
type: string
|
||||
description: |
|
||||
OAuth config ID for OAuth authentication.
|
||||
References the oauth_configs table.
|
||||
Only set when auth_type is "oauth".
|
||||
headers:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
description: |
|
||||
Custom headers to include in requests.
|
||||
Only used when auth_type is "headers".
|
||||
tools_to_execute:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |
|
||||
Include-only list for tools.
|
||||
["*"] => all tools are included
|
||||
[] => no tools are included
|
||||
["tool1", "tool2"] => include only the specified tools
|
||||
tools_to_auto_execute:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |
|
||||
List of tools that can be auto-executed without user approval.
|
||||
Must be a subset of tools_to_execute.
|
||||
["*"] => all executable tools can be auto-executed
|
||||
[] => no tools are auto-executed
|
||||
["tool1", "tool2"] => only specified tools can be auto-executed
|
||||
tool_pricing:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: number
|
||||
format: double
|
||||
description: |
|
||||
Per-tool cost in USD for execution.
|
||||
Key is the tool name, value is the cost per execution.
|
||||
Example: {"read_file": 0.001, "write_file": 0.002}
|
||||
allow_on_all_virtual_keys:
|
||||
type: boolean
|
||||
default: false
|
||||
description: |
|
||||
When true, this MCP client's tools are accessible to all virtual keys without requiring
|
||||
explicit per-key assignment. All tools are allowed by default. If a virtual key has an
|
||||
explicit MCP config for this client, that config takes precedence and overrides this behaviour.
|
||||
|
||||
ChatToolFunction:
|
||||
type: object
|
||||
description: Tool function definition
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
parameters:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
strict:
|
||||
type: boolean
|
||||
|
||||
MCPVKConfigResponse:
|
||||
type: object
|
||||
description: Per-virtual-key tool access configuration as returned in list/get responses
|
||||
properties:
|
||||
virtual_key_id:
|
||||
type: string
|
||||
description: ID of the virtual key
|
||||
virtual_key_name:
|
||||
type: string
|
||||
description: Display name of the virtual key
|
||||
tools_to_execute:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |
|
||||
Tools this virtual key is allowed to call on this MCP client.
|
||||
["*"] => all tools allowed
|
||||
["tool1", "tool2"] => only the specified tools
|
||||
|
||||
MCPClient:
|
||||
type: object
|
||||
description: Connected MCP client with its tools
|
||||
properties:
|
||||
config:
|
||||
$ref: '#/MCPClientConfig'
|
||||
tools:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/ChatToolFunction'
|
||||
state:
|
||||
$ref: '#/MCPConnectionState'
|
||||
vk_configs:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/MCPVKConfigResponse'
|
||||
description: Virtual key assignments for this MCP client
|
||||
|
||||
ExecuteToolRequest:
|
||||
oneOf:
|
||||
- title: Chat (Default)
|
||||
description: Chat format - uses ChatAssistantMessageToolCall schema
|
||||
$ref: '../../schemas/inference/chat.yaml#/ChatAssistantMessageToolCall'
|
||||
- title: Responses
|
||||
description: Responses format - uses ResponsesToolMessage schema
|
||||
$ref: '#/ResponsesToolMessage'
|
||||
description: |
|
||||
MCP tool execution request. The schema depends on the `format` query parameter:
|
||||
- `format=chat` or empty (default): Use `ChatAssistantMessageToolCall` schema
|
||||
- `format=responses`: Use `ResponsesToolMessage` schema
|
||||
|
||||
ExecuteToolResponse:
|
||||
oneOf:
|
||||
- title: Chat (Default)
|
||||
description: Chat format response
|
||||
$ref: '../../schemas/inference/chat.yaml#/ChatMessage'
|
||||
- title: Responses
|
||||
description: Responses format response
|
||||
$ref: '../../schemas/inference/responses.yaml#/ResponsesMessage'
|
||||
description: |
|
||||
MCP tool execution response.
|
||||
|
||||
ResponsesToolMessage:
|
||||
type: object
|
||||
description: Tool message for Responses API format
|
||||
required:
|
||||
- name
|
||||
properties:
|
||||
call_id:
|
||||
type: string
|
||||
description: Common call ID for tool calls and outputs
|
||||
name:
|
||||
type: string
|
||||
description: Tool function name (required for execution)
|
||||
arguments:
|
||||
type: string
|
||||
description: Tool function arguments as JSON string
|
||||
output:
|
||||
type: object
|
||||
description: Tool execution output
|
||||
additionalProperties: true
|
||||
action:
|
||||
type: object
|
||||
description: Tool action configuration
|
||||
additionalProperties: true
|
||||
error:
|
||||
type: string
|
||||
description: Error message if tool execution failed
|
||||
Reference in New Issue
Block a user