Override Types

Complete reference for catalog overrides. Overrides modify how API specs are interpreted without changing the original spec files.

Override Structure

All overrides share a common structure:

scope: string # What this override applies to
type: string # Override type (oauth, bearer, description, etc.)
strategy?: string # When to apply (always, when-missing, when-undeclared)
# ... type-specific properties

Scope Patterns

Pattern	Applies To
`*`	All operations in catalog
`serviceName/*`	All operations from an API
`serviceName/operationName`	Specific operation

More specific scopes take precedence over broader ones.

Strategies

Strategy	Behavior
`always`	Apply regardless of what spec declares
`when-missing`	Apply only if spec doesn’t define it
`when-undeclared`	Apply only if no security scheme is declared

Default strategy varies by override type.

Authentication Overrides

Fix or define authentication schemes for APIs.

oauth

Define OAuth 2.0 authentication.

type: oauth
schemeName: string # Security scheme name
grantType: string # OAuth grant type
authorizationUrl?: string # Authorization endpoint
tokenUrl: string # Token endpoint
scopes?: string[] # Required scopes
realm: string # Credential storage realm
normalizeHeaders?: boolean # Convert auth header params
strategy?: string # Default: when-undeclared

Grant Types:

Type	Description
`authorization_code`	Standard web flow with redirect
`client_credentials`	Machine-to-machine, no user
`refresh_token`	Token refresh flow

Example:

scope: github/*
type: oauth
schemeName: github_oauth
grantType: authorization_code
authorizationUrl: https://github.com/login/oauth/authorize
tokenUrl: https://github.com/login/oauth/access_token
scopes:
  - repo
  - user
realm: toolcog/github

bearer

Define HTTP Bearer token authentication.

type: bearer
schemeName: string # Security scheme name
realm?: string # Credential storage realm
normalizeHeaders?: boolean # Convert auth header params
strategy?: string # Default: when-undeclared

Example:

scope: myapi/*
type: bearer
schemeName: bearerAuth
normalizeHeaders: true
realm: myorg/myapi-realm

Header Normalization:

When normalizeHeaders: true, Toolcog:

Detects Authorization header parameters in the spec
Converts them to proper bearer security schemes
Removes the duplicate parameter

basic

Define HTTP Basic authentication.

type: basic
schemeName: string # Security scheme name
realm?: string # Credential storage realm
normalizeHeaders?: boolean # Convert auth header params
strategy?: string # Default: when-undeclared

Example:

scope: legacy-api/*
type: basic
schemeName: basicAuth
normalizeHeaders: true

apikey

Define API key authentication.

type: apikey
schemeName: string # Security scheme name
in: string # Where key goes (header, query, cookie)
name: string # Parameter name
realm?: string # Credential storage realm
normalizeHeaders?: boolean # Convert auth header params
strategy?: string # Default: when-undeclared

Locations:

Value	Description
`header`	API key in request header
`query`	API key in query string
`cookie`	API key in cookie

Example:

scope: weather-api/*
type: apikey
schemeName: apiKey
in: header
name: X-API-Key

Content Overrides

Modify operation descriptions and summaries.

description

Replace an operation’s description.

type: description
value: string # New description (supports multiline)
strategy?: string # Default: always

Example:

scope: stripe/customers.create
type: description
value: |
  Creates a new customer in your Stripe account.

  The customer object represents a customer of your business.
  Use this to store contact information and payment methods.

  Required parameters:
  - email: Customer's email address

  Optional parameters:
  - name: Customer's full name
  - metadata: Key-value pairs for custom data

summary

Replace an operation’s summary (short one-liner).

type: summary
value: string # New summary
strategy?: string # Default: always

Example:

scope: stripe/customers.create
type: summary
value: Create a new customer

Structure Overrides

Modify API structure and behavior.

server

Change the base URL for API calls.

type: server
url: string # New server URL
strategy?: string # Default: always

Example:

scope: myapi/*
type: server
url: https://staging-api.example.com

Use Cases:

Point to staging environments
Use custom domains
Switch API versions
Override production URLs for testing

deprecated

Mark an operation as deprecated.

type: deprecated
value: boolean # true to mark deprecated
strategy?: string # Default: always

Example:

scope: legacy-api/users.list
type: deprecated
value: true

Deprecated operations:

Still work but are de-prioritized in discovery
May show warnings in AI responses
Signal that alternatives should be used

strip

Remove examples and extensions from specs.

type: strip
examples?: boolean # Remove example values
extensions?: boolean # Remove x-* extensions
strategy?: string # Default: always

Example:

scope: verbose-api/*
type: strip
examples: true
extensions: true

Use Cases:

Reduce spec size for faster loading
Remove sensitive example data
Clean up vendor extensions

parameter

Modify a parameter’s properties.

type: parameter
name: string # Parameter name
description?: string # New description
required?: boolean # Whether required
strategy?: string # Default: always

Example:

scope: api/users.create
type: parameter
name: customer_id
description: The unique identifier for the customer (UUID format)
required: true

Common Properties

schemeName

Identifies the security scheme. Must match the scheme name used in operations’ security requirements.

schemeName: bearerAuth # Operations declare: security: [{ bearerAuth: [] }]

realm

Links to credential storage. Format: {owner}/{realm-name}.

realm: toolcog/github       # Toolcog-managed GitHub OAuth
realm: myorg/internal-api   # Organization's custom realm

Realms are configured separately with OAuth client credentials.

normalizeHeaders

Converts header-based auth parameters to proper security schemes.

Many APIs incorrectly declare auth as:

parameters:
  - name: Authorization
    in: header
    required: true

With normalizeHeaders: true, Toolcog:

Detects this pattern
Creates a proper security scheme
Removes the redundant parameter
Applies credentials automatically

strategy

Controls when the override applies.

always (default for most types):

strategy: always # Override regardless of spec

when-missing (for filling gaps):

strategy: when-missing # Only if spec doesn't define

when-undeclared (default for auth types):

strategy: when-undeclared # Only if no security declared

Override Order

When multiple overrides could apply to the same operation:

Operation-specific (api/operation) applies first
API-specific (api/*) applies second
Global (*) applies last

Within the same scope, overrides are applied in definition order.

Example:

# Applied third (most general)
- scope: "*"
  type: bearer
  schemeName: defaultAuth

# Applied second
- scope: stripe/*
  type: oauth
  schemeName: stripeOAuth

# Applied first (most specific)
- scope: stripe/customers.create
  type: description
  value: Custom description for this operation

Examples

Fix Header-Based Auth Across All Operations

- scope: "*"
  type: bearer
  schemeName: bearerAuth
  normalizeHeaders: true

Add OAuth to a Specific API

- scope: github/*
  type: oauth
  schemeName: github_oauth
  grantType: authorization_code
  authorizationUrl: https://github.com/login/oauth/authorize
  tokenUrl: https://github.com/login/oauth/access_token
  scopes:
    - repo
    - user:email
  realm: toolcog/github

Use Staging Server for Development

- scope: myapi/*
  type: server
  url: https://staging.myapi.com/v2

Improve Vague Operation Descriptions

- scope: payments/charge.create
  type: description
  value: |
    Creates a charge against a customer's payment method.

    The charge is captured immediately unless capture: false is set.
    Returns the charge object on success.

- scope: payments/charge.create
  type: summary
  value: Create a payment charge

Clean Up Verbose Specs

- scope: verbose-vendor/*
  type: strip
  examples: true
  extensions: true

Mark Legacy Operations

- scope: v1/*
  type: deprecated
  value: true

Validation

Overrides are validated when saved:

Required fields must be present for the override type
Scope patterns must be valid
URLs must be well-formed
Grant types must be recognized OAuth flows
Realm references must exist (for OAuth overrides)

Invalid overrides are rejected with specific error messages.

Next Steps

Overrides — Conceptual guide to overrides
Creating a Catalog — Set up catalogs with overrides
OAuth Services — Configure OAuth realms

MCP Clients

Agent SDKs

Integrations

Technology

Learn

Company

Override Types

Override Structure

Scope Patterns

Strategies

Authentication Overrides

oauth

bearer

basic

apikey

Content Overrides

description

summary

Structure Overrides

server

deprecated

strip

parameter

Common Properties

schemeName

realm

normalizeHeaders

strategy

Override Order

Examples

Fix Header-Based Auth Across All Operations

Add OAuth to a Specific API

Use Staging Server for Development

Improve Vague Operation Descriptions

Clean Up Verbose Specs

Mark Legacy Operations

Validation

Next Steps