YAML Schemas

Related Topics: Endpoints (endpoint types) | Type System (parameter types) | Configuration (runtime config) | Validation (check syntax)

This page provides an overview of all YAML configuration files in MXCP. Click through to detailed schema references for complete documentation.

Schema References

Schema	File Location	Description
Tool Schema	tools/*.yml	Tool endpoint definitions
Resource Schema	resources/*.yml	Resource endpoint definitions
Prompt Schema	prompts/*.yml	Prompt endpoint definitions
Site Configuration	mxcp-site.yml	Project configuration
User Configuration	~/.mxcp/config.yml	User-level settings and secrets

File Types Overview

Endpoint Definitions

Endpoints are the core building blocks of MXCP. Each type has its own schema:

Tools - Callable functions that AI agents can invoke:

mxcp: 1
tool:
  name: get_user
  description: Retrieve user by ID
  parameters:
    - name: user_id
      type: integer
  source:
    file: ../sql/get_user.sql

Resources - Data accessible via URI patterns:

mxcp: 1
resource:
  uri: "user://{user_id}/profile"
  name: User Profile
  source:
    file: ../sql/user_profile.sql

Prompts - Templated conversation starters:

mxcp: 1
prompt:
  name: analyze_data
  description: Analyze data with customizable focus
  parameters:
    - name: topic
      type: string
  messages:
    - role: system
      type: text
      prompt: "You are an expert analyst."
    - role: user
      type: text
      prompt: "Analyze: {{ topic }}"

Configuration Files

Site Configuration (mxcp-site.yml) - Project-level settings:

mxcp: 1
project: my-project
profile: default

extensions:
  - httpfs
  - parquet

profiles:
  default:
    duckdb:
      path: ./data/app.duckdb
    audit:
      enabled: true

User Configuration (~/.mxcp/config.yml) - User-level secrets and auth:

mxcp: 1
projects:
  my-project:
    profiles:
      default:
        secrets:
          - name: api_key
            type: api
            parameters:
              api_key: "${MY_API_KEY}"
        auth:
          provider: github
          github:
            client_id: "${GITHUB_CLIENT_ID}"
            client_secret: "${GITHUB_CLIENT_SECRET}"
            callback_path: /auth/github/callback
            auth_url: https://github.com/login/oauth/authorize
            token_url: https://github.com/login/oauth/access_token

Common Schema Elements

Schema Version

All MXCP YAML files start with the schema version:

mxcp: 1    # Required, always 1

Value Interpolation

User configuration supports dynamic value interpolation:

Syntax	Source	Example
${VAR}	Environment variable	${API_KEY}
vault://path#key	HashiCorp Vault	vault://secret/db#password
op://vault/item/field	1Password	op://Private/api/token
file://path	Local file	file:///etc/ssl/cert.pem

See User Configuration for complete interpolation documentation.

Parameters

Parameters are shared across tools, resources, and prompts:

parameters:
  - name: user_id          # Required: identifier
    type: integer          # Required: data type
    description: User ID   # Recommended: description
    default: null          # Optional: makes parameter optional
    minimum: 1             # Optional: validation constraint

See Type System for complete type documentation.

Source

Tools and resources require a source definition:

# Inline code
source:
  code: |
    SELECT * FROM users WHERE id = $user_id

# External file
source:
  file: ../sql/get_user.sql

Tests

All endpoint types support inline tests:

tests:
  - name: test_basic
    arguments:
      - key: user_id
        value: 1
    result_contains:
      name: "Alice"

See Testing for complete documentation.

Policies

Tools and resources support access control policies:

policies:
  input:
    - condition: "user.role == 'guest'"
      action: deny
      reason: "Guests cannot access this endpoint"
  output:
    - condition: "user.role != 'admin'"
      action: filter_fields
      fields: ["salary", "ssn"]

See Policies for complete documentation.

Validation

Validate all YAML files:

# Validate entire project
mxcp validate

# Validate specific file
mxcp validate tools/my-tool.yml

# Verbose output
mxcp validate --debug

Quick Reference

Required Fields by Type

Type	Required Fields
Tool	mxcp, tool.name, tool.source
Resource	mxcp, resource.uri, resource.source
Prompt	mxcp, prompt.name, prompt.messages
Site Config	mxcp, project, profile
User Config	mxcp

Common Optional Fields

All endpoint types (tools, resources, prompts) support these optional fields:

Field	Default	Description
description	null	Human-readable description
enabled	true	Set to false to disable the endpoint
tags	[]	List of tags for categorization
tests	[]	Inline test definitions
policies	null	Access control policies

Tools and resources also support:

Field	Default	Description
language	"sql"	Source language: "sql" or "python"

Data Types

Type	Description	Example
string	Text value	"hello"
integer	Whole number	42
number	Decimal number	3.14
boolean	True/false	true
array	List of items	[1, 2, 3]
object	Key-value pairs	{key: value}

Policy Actions

Action	Type	Description
deny	input	Block the request
filter_fields	output	Remove specified fields
mask_fields	output	Mask field values
filter_sensitive_fields	output	Remove sensitive fields

Next Steps

• Tool Schema - Complete tool reference
• Resource Schema - Complete resource reference
• Prompt Schema - Complete prompt reference
• Site Configuration - Project configuration
• User Configuration - Secrets and authentication