447 lines
14 KiB
YAML
447 lines
14 KiB
YAML
# 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
|