Menu

Declarations

Learn the paso YAML declaration format.

A paso declaration is a usepaso.yaml file that describes an API and exposes specific capabilities as MCP tools.

File Structure

The declaration has three main sections:

# API metadata
name: string
version: string
base_url: string
auth: object

# What to expose
capabilities:
  - name: string
    description: string
    method: string
    path: string
    permission: string
    inputs: array

# What to hide
forbidden:
  paths: array
  methods: array

Top-Level Fields

name (required)

A unique identifier for the API. Used in logs and tool names.

name: github-api

version (required)

The API version.

version: "1.0.0"

base_url (required)

The root URL of the API.

base_url: https://api.github.com

auth (optional)

Authentication configuration. Supported types: bearer, api_key, basic, oauth2.

auth:
  type: bearer
  env_var: GITHUB_TOKEN
auth:
  type: api_key
  env_var: STRIPE_API_KEY
  header: X-API-Key

If auth is omitted, the server runs without authentication.

Capabilities

A capability exposes a single API endpoint as an MCP tool.

name (required)

The tool name exposed to Claude. Must be unique within the declaration.

- name: list_repos

description (required)

What the tool does. Used by Claude to decide when to call it.

  description: List all repositories for the authenticated user

method (required)

HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.

  method: GET

path (required)

The endpoint path relative to base_url. Use {param} for path variables.

  path: /repos/{owner}/{repo}/issues

permission (required)

One of read, write, admin. See Permissions & Safety.

  permission: write

If true, Claude must ask the user for approval before calling this tool.

  consent_required: true

inputs (optional)

Array of input parameters. Can come from query parameters, path variables, or request body.

  inputs:
    - name: owner
      type: string
      required: true
      description: Repository owner username

    - name: per_page
      type: number
      description: Results per page
      default: 30

    - name: status
      type: string
      enum:
        - open
        - closed
        - all

Input Field Types

  • string — text
  • number — integer or float
  • boolean — true/false
  • object — JSON object
  • array — JSON array

constraints (optional)

Rate limiting and bounds. See Permissions & Safety.

  constraints:
    rate_limit: 10
    max_items: 100
    max_value: 1000

Forbidden List

Hide specific paths or methods globally.

forbidden:
  paths:
    - /admin/*
    - /internal/settings
  methods:
    - DELETE

Capabilities that match forbidden paths or methods will not be exposed, even if declared.

Complete Example

name: github-api
version: "1.0.0"
base_url: https://api.github.com
auth:
  type: bearer
  env_var: GITHUB_TOKEN

capabilities:
  - name: list_repos
    description: List repositories for the authenticated user
    method: GET
    path: /user/repos
    permission: read
    inputs:
      - name: type
        type: string
        enum:
          - all
          - owner
          - public
        default: all
      - name: per_page
        type: number
        default: 30

  - name: create_repo
    description: Create a new repository
    method: POST
    path: /user/repos
    permission: write
    consent_required: true
    inputs:
      - name: name
        type: string
        required: true
        description: The name of the repository
      - name: description
        type: string
      - name: private
        type: boolean
        default: false

  - name: create_issue
    description: Create an issue in a repository
    method: POST
    path: /repos/{owner}/{repo}/issues
    permission: write
    inputs:
      - name: owner
        type: string
        required: true
      - name: repo
        type: string
        required: true
      - name: title
        type: string
        required: true
      - name: body
        type: string

  - name: list_issues
    description: List issues in a repository
    method: GET
    path: /repos/{owner}/{repo}/issues
    permission: read
    constraints:
      rate_limit: 5
      max_items: 100
    inputs:
      - name: owner
        type: string
        required: true
      - name: repo
        type: string
        required: true
      - name: state
        type: string
        enum:
          - open
          - closed
          - all
        default: open

forbidden:
  paths:
    - /admin/*
    - /app/installations/*/suspended

Validation

Check your declaration:

usepaso validate

This verifies:

  • All required fields are present
  • Field types are correct
  • Auth configuration is valid
  • No duplicate capability names
  • Path variables match capability inputs

Your declaration is complete.

You now know every field in a usepaso.yaml file.

Next, you might want to: