Variables

Variables let you pass parameters when connecting to a catalog. This enables multi-tenant scenarios where the same catalog serves different customers with different configuration.

What Variables Are

A variable is a named parameter that:

• Is defined in your catalog
• Is provided by the MCP client when connecting
• Gets substituted into API calls at runtime

When to Use Variables

Multi-Tenant APIs

Your API requires a tenant identifier:

https://api.example.com/tenants/{tenant_id}/customers

Define a tenant_id variable. Each customer provides their own tenant ID when connecting.

Environment-Specific Configuration

Different customers use different servers:

Variable: api_base_url
Customer A: https://customer-a.example.com
Customer B: https://customer-b.example.com

Custom Headers

Your API requires a customer-specific header:

Header: X-Customer-ID
Variable: customer_id

Defining Variables

In the Dashboard

1. Navigate to your catalog
2. Go to Variables
3. Click Add Variable
4. Configure the variable
5. Save

Variable Properties

Passing Variables

Variables are passed via the MCP connection URL:

https://mcp.toolcog.com/mycompany/saas-api?tenant_id=acme

Or in the MCP configuration:

{
  "mcpServers": {
    "my-api": {
      "url": "https://mcp.toolcog.com/mycompany/saas-api",
      "variables": {
        "tenant_id": "acme"
      }
    }
  }
}

Variable Resolution

When AI executes an operation, variables are resolved:

In Path Parameters

# Catalog variable mapping:
path: /tenants/{tenant_id}/customers
maps_to: $tenant_id # Uses the tenant_id variable

In Headers

# Catalog variable mapping:
header: X-Tenant-ID
value: $tenant_id

In Query Parameters

# Catalog variable mapping:
query: tenant
value: $tenant_id

In Server URLs

# Catalog variable mapping:
server: https://{customer_subdomain}.api.example.com
customer_subdomain: $customer_subdomain

Hierarchical Scoping

Variables can be scoped at different levels:

Global Variables

Apply to all operations:

scope: "*"
variable: tenant_id
maps_to: path.tenant_id

Per-API Variables

Apply to operations from a specific API:

scope: "myapi/*"
variable: api_version
maps_to: header.X-API-Version

Per-Operation Variables

Apply to specific operations:

scope: "myapi/users.create"
variable: region
maps_to: query.region

Use Cases

SaaS Platform Integration

A SaaS provider wants customers to use their API via Toolcog:

1. Create a catalog for your SaaS API
2. Define variables: tenant_id, api_key
3. Share the catalog URL template with customers
4. Each customer connects with their own values

Customer A: https://mcp.toolcog.com/saas/api?tenant_id=a&api_key=key_a
Customer B: https://mcp.toolcog.com/saas/api?tenant_id=b&api_key=key_b

Regional Deployment

An API has different endpoints per region:

1. Define variable: region
2. Map to server URL: https://{region}.api.example.com
3. Customers connect with their region

US: https://mcp.toolcog.com/mycompany/api?region=us
EU: https://mcp.toolcog.com/mycompany/api?region=eu

White-Label API

You want to provide API access to your customers’ customers:

1. Define variable: customer_id
2. Map to required header: X-Customer-ID
3. Each end user connects with their customer’s ID

Variable Validation

Toolcog validates variables when connecting:

• Required variables — Connection fails if not provided
• Format validation — Checks against defined patterns
• Default fallback — Uses default if not provided and not required

Security Considerations

Variables appear in URLs and logs. For sensitive values:

• Use credentials instead of variables for secrets
• Variables are for tenant identifiers, not passwords
• Consider what’s logged in your audit trail

Next Steps

• Overrides — Fix and customize API specs
• Creating a Catalog — Set up your catalog