Skip to content

tools.md

Latest commit

 

History

History
1052 lines (858 loc) · 23.4 KB

tools.md

File metadata and controls

1052 lines (858 loc) · 23.4 KB

WebMCP Tool Reference

This document provides a complete reference for all WebMCP tools available in Cortex. Tools are organized by category.

Provider Management Tools

Tools for managing AI providers in Cortex.

cortex_list_providers

List all configured AI providers with status, latency, and auth state.

Registration: Bucket A (Base Tool) - Always available when authenticated

Input Schema: None (empty object)

{
  type: 'object',
  properties: {},
  additionalProperties: false
}

Output:

interface ProviderSummary {
  name: string
  type: string
  status: 'online' | 'offline' | 'error'
  latency: number
  healthy: boolean
  authenticated: boolean
}[]

Example:

const result = await client.executeTool('cortex_list_providers', {})
// Returns:
// [
//   { name: 'anthropic', type: 'anthropic', status: 'online', latency: 45, healthy: true, authenticated: true },
//   { name: 'openai', type: 'openai', status: 'online', latency: 32, healthy: true, authenticated: true }
// ]

cortex_get_provider

Get detailed configuration for a specific provider including models, credentials, rate limits, and all settings.

Registration: Bucket B (Dynamic Tool) - Available on Providers page

Input Schema:

{
  type: 'object',
  properties: {
    provider_name: {
      type: 'string',
      description: 'The name of the provider to get details for'
    }
  },
  required: ['provider_name'],
  additionalProperties: false
}

Output:

interface ProviderDetail {
  name: string
  type: string
  status: 'online' | 'offline' | 'error'
  latency: number
  healthy: boolean
  authenticated: boolean
  base_url: string
  enabled: boolean
  auth_method: string
  default_model: string
  description: string
  supports_streaming: boolean
  max_tokens?: number
  timeout_ms: number
  free_only: boolean
  allowed_models?: string[] | null
  models?: Array<{
    id: string
    display_name: string
    enabled: boolean
  }>
  credentials?: {
    api_keys?: Array<{ masked: string; index: number }>
    oauth?: { configured: boolean; authenticated: boolean }
  }
  rate_limits?: {
    requests_per_minute?: number | null
    tokens_per_minute?: number | null
  }
}

Example:

const result = await client.executeTool('cortex_get_provider', {
  provider_name: 'anthropic'
})

cortex_create_provider

Add a new AI provider to Cortex.

Registration: Bucket B (Dynamic Tool) - Available on Providers page

Tags: destructive - May require human confirmation

Input Schema:

{
  type: 'object',
  properties: {
    type: {
      type: 'string',
      description: 'The type of provider (e.g., "anthropic", "openai", "gemini")'
    },
    name: {
      type: 'string',
      description: 'Optional custom name for the provider (defaults to type)'
    },
    enabled: {
      type: 'boolean',
      description: 'Whether the provider should be enabled (default: true)',
      default: true
    },
    base_url: {
      type: 'string',
      description: 'Optional custom base URL for the provider API'
    },
    api_key: {
      type: 'string',
      description: 'The API key for authentication'
    },
    default_model: {
      type: 'string',
      description: 'The default model to use for this provider'
    },
    auth_method: {
      type: 'string',
      enum: ['api_key', 'oauth'],
      description: 'The authentication method (default: api_key)'
    },
    temperature: {
      type: 'number',
      description: 'Default temperature for completions (0.0 to 2.0)',
      minimum: 0,
      maximum: 2
    },
    max_tokens: {
      type: 'number',
      description: 'Maximum tokens for completions'
    }
  },
  required: ['type', 'api_key'],
  additionalProperties: false
}

Output:

{
  success: boolean
  provider: string
  message: string
}

Example:

const result = await client.executeTool('cortex_create_provider', {
  type: 'openai',
  api_key: 'sk-...',
  default_model: 'gpt-4'
})

cortex_update_provider

Update provider configuration.

Registration: Bucket B (Dynamic Tool) - Available on Providers page

Input Schema:

{
  type: 'object',
  properties: {
    provider_name: {
      type: 'string',
      description: 'The name of the provider to update'
    },
    enabled: {
      type: 'boolean',
      description: 'Whether the provider should be enabled'
    },
    default_model: {
      type: 'string',
      description: 'The default model to use for this provider'
    },
    add_api_keys: {
      type: 'array',
      items: { type: 'string' },
      description: 'API keys to add to the provider'
    },
    remove_api_keys: {
      type: 'array',
      items: { type: 'string' },
      description: 'API keys to remove from the provider'
    },
    base_url: {
      type: 'string',
      description: 'Custom base URL for the provider API'
    },
    auth_method: {
      type: 'string',
      enum: ['api_key', 'oauth', 'auto'],
      description: 'The authentication method'
    },
    temperature: {
      type: 'number',
      description: 'Default temperature for completions'
    },
    max_tokens: {
      type: 'number',
      description: 'Maximum tokens for completions'
    },
    free_only: {
      type: 'boolean',
      description: 'Whether to only use free models'
    },
    allowed_models: {
      type: 'array',
      items: { type: 'string' },
      description: 'List of allowed model IDs (null for all models)'
    }
  },
  required: ['provider_name'],
  additionalProperties: false
}

Output:

{
  success: boolean
  provider: string
  message: string
}

Example:

const result = await client.executeTool('cortex_update_provider', {
  provider_name: 'openai',
  default_model: 'gpt-4-turbo',
  enabled: true
})

cortex_delete_provider

Remove a provider permanently.

Registration: Bucket B (Dynamic Tool) - Available on Providers page

Tags: destructive - Requires human confirmation

Input Schema:

{
  type: 'object',
  properties: {
    provider_name: {
      type: 'string',
      description: 'The name of the provider to delete'
    }
  },
  required: ['provider_name'],
  additionalProperties: false
}

Output:

{
  success: boolean
  provider: string
  message: string
}

Example:

const result = await client.executeTool('cortex_delete_provider', {
  provider_name: 'old-provider'
})

cortex_test_provider

Test provider credentials and connectivity.

Registration: Bucket B (Dynamic Tool) - Available on Providers page

Input Schema:

{
  type: 'object',
  properties: {
    provider_name: {
      type: 'string',
      description: 'The name of the provider to test'
    }
  },
  required: ['provider_name'],
  additionalProperties: false
}

Output:

interface TestProviderResult {
  success: boolean
  latency?: number
  error?: string
  models_available?: number
}

Example:

const result = await client.executeTool('cortex_test_provider', {
  provider_name: 'anthropic'
})
// Returns: { success: true, latency: 234, models_available: 8 }

cortex_toggle_provider

Enable or disable a provider.

Registration: Bucket B (Dynamic Tool) - Available on Providers page

Input Schema:

{
  type: 'object',
  properties: {
    provider_name: {
      type: 'string',
      description: 'The name of the provider to toggle'
    },
    enabled: {
      type: 'boolean',
      description: 'Whether to enable (true) or disable (false) the provider'
    }
  },
  required: ['provider_name', 'enabled'],
  additionalProperties: false
}

Output:

interface ToggleProviderResult {
  success: boolean
  new_status: boolean
}

Example:

const result = await client.executeTool('cortex_toggle_provider', {
  provider_name: 'openai',
  enabled: false
})
// Returns: { success: true, new_status: false }

Tool Tags

Tools can have tags that indicate special behavior:

Tag Description
destructive Tool performs destructive operations. May require human confirmation.
batch Tool performs batch operations on multiple resources.
test Tool tests or verifies resources.
read Tool only reads data, no side effects.
write Tool modifies data.
meta Tool provides metadata about the system.

Discovery Tools

Tools for discovering available WebMCP tools and capabilities.

cortex_discover_tools

List available tools by category/capability. Optionally filter by category or tags.

Registration: Bucket A (Base Tool) - Always available when authenticated

Input Schema:

{
  type: 'object',
  properties: {
    category: {
      type: 'string',
      enum: ['providers', 'api_keys', 'teams', 'virtual_models', 'aliases', 'patterns', 'quotas', 'metrics', 'discovery', 'batch', 'verification'],
      description: 'Filter to a specific category (optional)'
    },
    includeTags: {
      type: 'array',
      items: { type: 'string' },
      description: 'Only include tools with these tags'
    },
    excludeTags: {
      type: 'array',
      items: { type: 'string' },
      description: 'Exclude tools with these tags'
    }
  },
  additionalProperties: false
}

Output:

interface DiscoverToolsResult {
  version: string
  toolCount: number
  categories: Record<ToolCategory, ToolCapability[]>
  capabilities: {
    providers: boolean
    apiKeys: boolean
    teams: boolean
    virtualModels: boolean
    aliases: boolean
    patterns: boolean
    quotas: boolean
    metrics: boolean
    batch: boolean
    verification: boolean
  }
}

Example:

const result = await client.executeTool('cortex_discover_tools', {
  category: 'providers'
})
// Returns tools in the providers category

cortex_get_capabilities

Return WebMCP version and features.

Registration: Bucket A (Base Tool) - Always available when authenticated

Input Schema: None (empty object)

{
  type: 'object',
  properties: {},
  additionalProperties: false
}

Output:

interface CapabilitiesResult {
  version: string
  features: {
    toolDiscovery: boolean
    batchOperations: boolean
    verificationTools: boolean
    errorRecovery: boolean
    retryableErrors: boolean
    rollbackSupport: boolean
  }
  categories: ToolCategory[]
  toolCount: number
  supportedOperations: string[]
  limits: {
    maxBatchSize: number
    maxRetries: number
    defaultTimeoutMs: number
  }
}

Example:

const result = await client.executeTool('cortex_get_capabilities', {})
// Returns WebMCP capabilities and limits

Batch Operations Tools

Tools for performing operations on multiple resources at once.

cortex_delete_providers

Delete multiple providers in a single batch operation.

Registration: Bucket B (Dynamic Tool)

Tags: destructive, batch - Requires human confirmation

Input Schema:

{
  type: 'object',
  properties: {
    provider_names: {
      type: 'array',
      items: { type: 'string' },
      description: 'List of provider names to delete',
      minItems: 1,
      maxItems: 50
    },
    confirm: {
      type: 'boolean',
      description: 'Confirmation flag (must be true to proceed)',
      default: false
    }
  },
  required: ['provider_names'],
  additionalProperties: false
}

Output:

interface BatchDeleteResult {
  total: number
  succeeded: number
  failed: number
  results: BatchOperationResult[]
}

Example:

const result = await client.executeTool('cortex_delete_providers', {
  provider_names: ['old-provider-1', 'old-provider-2'],
  confirm: true
})
// Returns batch delete results

cortex_test_all_providers

Test connectivity and credentials for all providers.

Registration: Bucket B (Dynamic Tool)

Tags: batch, test

Input Schema:

{
  type: 'object',
  properties: {
    include_disabled: {
      type: 'boolean',
      description: 'Whether to test disabled providers (default: false)',
      default: false
    },
    timeout_ms: {
      type: 'number',
      description: 'Timeout for each test in milliseconds (default: 30000)',
      minimum: 5000,
      maximum: 120000
    }
  },
  additionalProperties: false
}

Output:

interface TestAllProvidersResult {
  total: number
  succeeded: number
  failed: number
  skipped: number
  results: Array<{
    provider: string
    success: boolean
    latency?: number
    error?: string
    modelsAvailable?: number
  }>
}

Example:

const result = await client.executeTool('cortex_test_all_providers', {
  include_disabled: false
})
// Returns test results for all providers

cortex_batch_update

Perform batch updates on providers, API keys, or teams with optional automatic rollback.

Registration: Bucket B (Dynamic Tool)

Tags: batch, destructive - Requires human confirmation

Input Schema:

{
  type: 'object',
  properties: {
    updates: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          type: {
            type: 'string',
            enum: ['provider', 'api_key', 'team'],
            description: 'The type of resource to update'
          },
          identifier: {
            oneOf: [
              { type: 'string' },
              { type: 'number' }
            ],
            description: 'The resource identifier (name or ID)'
          },
          updates: {
            type: 'object',
            description: 'The updates to apply'
          }
        },
        required: ['type', 'identifier', 'updates']
      },
      description: 'List of updates to perform',
      minItems: 1,
      maxItems: 50
    },
    enable_rollback: {
      type: 'boolean',
      description: 'Enable automatic rollback on failure (default: true)',
      default: true
    },
    stop_on_error: {
      type: 'boolean',
      description: 'Stop processing on first error (default: true)',
      default: true
    }
  },
  required: ['updates'],
  additionalProperties: false
}

Output:

interface BatchUpdateResult {
  total: number
  succeeded: number
  failed: number
  rolledBack: number
  results: BatchOperationResult[]
  rollbackLog?: Array<{
    identifier: string | number
    type: string
    originalValue: unknown
    restoredValue: unknown
  }>
}

Example:

const result = await client.executeTool('cortex_batch_update', {
  updates: [
    { type: 'provider', identifier: 'openai', updates: { enabled: true } },
    { type: 'provider', identifier: 'anthropic', updates: { enabled: true } }
  ],
  enable_rollback: true
})
// Returns batch update results

Verification Tools

Tools for verifying configuration and status of resources.

cortex_verify_provider_status

Verify that a provider is correctly configured and operational.

Registration: Bucket B (Dynamic Tool)

Tags: verification, test

Input Schema:

{
  type: 'object',
  properties: {
    provider_name: {
      type: 'string',
      description: 'The name of the provider to verify'
    },
    test_connectivity: {
      type: 'boolean',
      description: 'Whether to perform a connectivity test (default: true)',
      default: true
    }
  },
  required: ['provider_name'],
  additionalProperties: false
}

Output:

interface ProviderVerificationResult {
  provider_name: string
  valid: boolean
  checks: VerificationCheck[]
  issues: string[]
  recommendations: string[]
  details: {
    configured: boolean
    enabled: boolean
    authenticated: boolean
    has_credentials: boolean
    has_models: boolean
    online: boolean
    latency_ms?: number
    models_count?: number
  }
}

Example:

const result = await client.executeTool('cortex_verify_provider_status', {
  provider_name: 'anthropic',
  test_connectivity: true
})
// Returns verification results

cortex_verify_key_status

Verify that an API key is correctly configured and operational.

Registration: Bucket B (Dynamic Tool)

Tags: verification, test

Input Schema:

{
  type: 'object',
  properties: {
    key_id: {
      type: 'number',
      description: 'The ID of the API key to verify'
    }
  },
  required: ['key_id'],
  additionalProperties: false
}

Output:

interface KeyVerificationResult {
  key_id: number
  key_name: string
  valid: boolean
  checks: VerificationCheck[]
  issues: string[]
  recommendations: string[]
  details: {
    exists: boolean
    enabled: boolean
    has_team: boolean
    team_enabled: boolean
    has_providers: boolean
    has_models: boolean
    within_quota: boolean
  }
}

Example:

const result = await client.executeTool('cortex_verify_key_status', {
  key_id: 42
})
// Returns verification results

Error Codes

All tools return standardized error codes organized into categories:

Provider Errors (1xx)

Code Description Retryable Suggestion
PROVIDER_NOT_FOUND Provider does not exist No Use cortex_list_providers to see available providers
PROVIDER_AUTH_FAILED Authentication failed No Check API key or OAuth credentials
PROVIDER_OFFLINE Provider is offline Yes Wait and try again
PROVIDER_DISABLED Provider is disabled No Use cortex_toggle_provider to enable
PROVIDER_ALREADY_EXISTS Provider name already exists No Use a different name
PROVIDER_TEST_FAILED Connectivity test failed Yes Check network and credentials
PROVIDER_TIMEOUT Provider request timed out Yes Try again or check status
PROVIDER_RATE_LIMITED Rate limit exceeded Yes Wait before retrying

API Key Errors (2xx)

Code Description Retryable Suggestion
KEY_NOT_FOUND API key does not exist No Use cortex_list_api_keys to see available keys
KEY_REVOKED Key has been revoked No Create a new key
KEY_EXPIRED Key has expired No Create a new key
KEY_DISABLED Key is disabled No Enable in settings
KEY_QUOTA_EXCEEDED Key quota exceeded Yes Wait or increase limits
KEY_ALREADY_EXISTS Key name already exists No Use a different name
KEY_INVALID_FORMAT Key format is invalid No Check format for provider

Team Errors (3xx)

Code Description Retryable Suggestion
TEAM_NOT_FOUND Team does not exist No Use cortex_list_teams
TEAM_DISABLED Team is disabled No Enable in team settings
TEAM_QUOTA_EXCEEDED Team quota exceeded Yes Wait or increase limits
TEAM_HAS_DEPENDENCIES Team has API keys assigned No Reassign keys before deleting

Configuration Errors (4xx)

Code Description Retryable Suggestion
CONFIG_INVALID Configuration is invalid No Check format and values
CONFIG_MISSING_REQUIRED Required field missing No Provide all required fields
CONFIG_TYPE_MISMATCH Wrong type No Check expected type
CONFIG_VALUE_OUT_OF_RANGE Value out of range No Adjust the value

Network Errors (5xx)

Code Description Retryable Suggestion
NETWORK_ERROR Network error Yes Check connection
NETWORK_TIMEOUT Request timed out Yes Try again
NETWORK_UNREACHABLE Network unreachable Yes Check connection
CONNECTION_REFUSED Connection refused Yes Service may be restarting
SSL_ERROR SSL certificate error No Check certificate

Validation Errors (6xx)

Code Description Retryable Suggestion
INVALID_INPUT Input validation failed No Check format and values
INVALID_PROVIDER_NAME Invalid provider name No Use lowercase, numbers, hyphens
INVALID_MODEL_ID Invalid model ID No Check model ID syntax
INVALID_TEAM_ID Invalid team ID No Must be positive integer
INVALID_KEY_ID Invalid API key ID No Must be positive integer
INVALID_ALIAS_NAME Invalid alias name No Use lowercase, numbers, hyphens
INVALID_PATTERN Invalid pattern format No Check pattern syntax

System Errors (7xx)

Code Description Retryable Suggestion
INTERNAL_ERROR Internal server error Yes Try again or contact support
STORAGE_ERROR Storage error Yes Try again
PERMISSION_DENIED Permission denied No Check user permissions
AUTHENTICATION_REQUIRED Authentication required No Log in
SESSION_EXPIRED Session expired No Log in again
SERVICE_UNAVAILABLE Service unavailable Yes Try again later
FEATURE_NOT_ENABLED Feature not enabled No Contact administrator

Execution Errors (8xx)

Code Description Retryable Suggestion
EXECUTION_ERROR Tool execution failed Yes Try again
EXECUTION_CANCELLED Execution cancelled Yes Try again
EXECUTION_TIMEOUT Execution timed out Yes Try simpler parameters
BATCH_PARTIAL_FAILURE Some batch ops failed No Check individual results
ROLLBACK_FAILED Rollback failed No Manual intervention required

Tool Chaining Examples

WebMCP tools can be chained together for complex operations:

Example 1: Verify and Update Provider

// 1. Discover available tools
const tools = await client.executeTool('cortex_discover_tools', {
  category: 'providers'
})

// 2. Verify provider status
const verification = await client.executeTool('cortex_verify_provider_status', {
  provider_name: 'openai',
  test_connectivity: true
})

// 3. If issues found, update provider
if (!verification.data.valid) {
  const update = await client.executeTool('cortex_update_provider', {
    provider_name: 'openai',
    enabled: true
  })
}

Example 2: Batch Test with Error Recovery

// 1. Test all providers
const testResults = await client.executeTool('cortex_test_all_providers', {})

// 2. Collect failed providers
const failedProviders = testResults.data.results
  .filter(r => !r.success)
  .map(r => r.provider)

// 3. Verify each failed provider
for (const provider of failedProviders) {
  const verify = await client.executeTool('cortex_verify_provider_status', {
    provider_name: provider
  })
  console.log(`${provider}: ${verify.data.issues.join(', ')}`)
}

Example 3: Batch Update with Rollback

// Batch update with automatic rollback on failure
const result = await client.executeTool('cortex_batch_update', {
  updates: [
    { type: 'provider', identifier: 'provider1', updates: { enabled: false } },
    { type: 'provider', identifier: 'provider2', updates: { enabled: false } },
    { type: 'provider', identifier: 'provider3', updates: { enabled: false } }
  ],
  enable_rollback: true,
  stop_on_error: true
})

// Check if rollback occurred
if (result.data.rolledBack > 0) {
  console.log('Some updates were rolled back due to errors')
}

Adding New Tools

To add new WebMCP tools, see the Migration Guide.