# paso — llms-full.txt
# Comprehensive reference for AI crawlers and language models. See https://llmstxt.org

> paso is an open-source MCP server generator. Declare your API's capabilities in a YAML file, and paso generates a live MCP server. No protocol code to write. Available for Node.js and Python with identical behavior.

## Key Facts

- Name: paso (product name), usepaso (CLI and packages)
- Website: https://usepaso.dev
- Package: npm install usepaso / pip install usepaso
- License: Apache 2.0
- Self-hosted: no cloud dependency, no SaaS
- Generates: a live MCP server from a YAML declaration
- Dual SDK: Node.js (TypeScript) and Python — same CLI, same output, same declaration format

## Declaration Format

A usepaso.yaml file has three sections: version, service, and capabilities.

```yaml
version: "1.0"

service:
  name: Sentry
  description: Error monitoring for software teams
  base_url: https://sentry.io/api/0
  auth:
    type: bearer

capabilities:
  - name: list_issues
    description: List issues for a project
    method: GET
    path: /projects/{organization_slug}/{project_slug}/issues/
    permission: read
    inputs:
      organization_slug:
        type: string
        required: true
        description: The organization slug
        in: path
      project_slug:
        type: string
        required: true
        description: The project slug
        in: path
      query:
        type: string
        required: false
        description: Search query
        in: query
    output:
      type: array
      description: List of issues
    constraints:
      - max_per_request: 100

permissions:
  read:
    - list_issues
    - get_issue
  write:
    - resolve_issue
  admin:
    - delete_issue
  forbidden:
    - transfer_organization
```

### Service Object

- name (string, required): Service display name
- description (string, required): What the service does
- base_url (string, required): API base URL
- auth (object): Authentication config
  - type (string, required): bearer | api_key | oauth2 | none
  - header (string, optional): Custom auth header name (default: Authorization)
  - prefix (string, optional): Token prefix (default: Bearer for bearer type)

### Capability Object

- name (string, required): Unique identifier, becomes the MCP tool name
- description (string, required): What the capability does — agents read this
- method (string, required): HTTP method (GET, POST, PUT, PATCH, DELETE)
- path (string, required): URL path with {param} placeholders
- permission (string): read | write | admin
- consent_required (boolean): If true, agents must confirm before executing
- inputs (object): Keyed by parameter name
  - type (string): string | number | integer | boolean | array | object
  - required (boolean)
  - description (string)
  - in (string): path | query | body | header
  - default (any)
  - values (array): Allowed enum values
- output (object):
  - type (string): string | number | object | array | boolean
  - description (string)
- constraints (array):
  - max_per_hour (number): Rate limit
  - max_per_request (number): Pagination limit
  - max_value (number): Maximum numeric value
  - requires_field (string): Field dependency

### Permissions Object

- read (array of capability names)
- write (array of capability names)
- admin (array of capability names)
- forbidden (array of capability names): Excluded from MCP server entirely

## CLI Commands

### usepaso init
Scaffold a new declaration.
- --name <name>: Set service name
- --from-openapi <path>: Generate from OpenAPI spec (JSON or YAML)

### usepaso validate
Check declaration against the spec.
- --strict: Enable best-practice warnings (missing consent_required on DELETE, short descriptions, no constraints on write capabilities, no permissions section)
- --json: Machine-readable output

### usepaso inspect
Preview MCP tools generated from the declaration.
- --json: Machine-readable output

### usepaso test [capability]
Test a capability with a real HTTP request.
- -p key=value: Set parameter
- --all: Test all capabilities
- --dry-run: Preview request without sending
- --verbose: Show full request and response
- --timeout <ms>: Request timeout
- -f <path>: Path to declaration file (default: ./usepaso.yaml)

### usepaso serve
Start an MCP server from the declaration using stdio transport.
- --watch: Reload on file changes

Auth token: set USEPASO_AUTH_TOKEN environment variable.

### usepaso doctor
Diagnose setup. Checks: file exists, YAML parses, validation passes, USEPASO_AUTH_TOKEN set, base URL reachable.

### usepaso completion
Generate shell completions.
- --shell bash|zsh|fish

### usepaso version
Print version number.

## Programmatic API

### Node.js
```typescript
import { parseFile, parseString, validate, parseAndValidate, parseFileAndValidate, generateMcpServer, buildRequest, executeRequest, formatError, generateFromOpenApi } from 'usepaso';
```

### Python
```python
from usepaso import parse_file, parse_string, validate, parse_and_validate, parse_file_and_validate, generate_mcp_server, build_request, execute_request, format_error
```

### Function Reference

| Function | Description |
|---|---|
| parseFile / parse_file | Parse a YAML file into a PasoDeclaration |
| parseString / parse_string | Parse a YAML string into a PasoDeclaration |
| validate | Validate a declaration, returns ValidationError[] |
| parseAndValidate / parse_and_validate | Parse string + validate. Throws on errors |
| parseFileAndValidate / parse_file_and_validate | Parse file + validate. Throws on errors |
| generateMcpServer / generate_mcp_server | Generate an MCP server from a declaration |
| buildRequest / build_request | Build an HTTP request from a capability + args |
| executeRequest / execute_request | Execute a built request, returns status + body |
| formatError / format_error | Format an error response with contextual help |
| generateFromOpenApi | Convert OpenAPI spec to YAML declaration (Node.js only) |

## Documentation

- Quick Start: https://usepaso.dev/docs/getting-started/
- Installation: https://usepaso.dev/docs/getting-started/installation/
- OpenAPI Import: https://usepaso.dev/docs/getting-started/openapi-import/
- Declarations: https://usepaso.dev/docs/concepts/declarations/
- Permissions & Safety: https://usepaso.dev/docs/concepts/permissions/
- Claude Desktop Setup: https://usepaso.dev/docs/guides/claude-desktop/
- Cursor Setup: https://usepaso.dev/docs/guides/cursor/
- Testing: https://usepaso.dev/docs/guides/testing/
- Programmatic Usage: https://usepaso.dev/docs/guides/programmatic-usage/
- Troubleshooting: https://usepaso.dev/docs/guides/doctor/
- CLI Reference: https://usepaso.dev/docs/api/cli/
- Declaration Spec: https://usepaso.dev/docs/api/declaration-spec/
- Examples: https://usepaso.dev/docs/examples/

## Blog

- How to Create an MCP Server: https://usepaso.dev/blog/how-to-create-an-mcp-server/
- How to Make Your API Work with Claude: https://usepaso.dev/blog/how-to-make-your-api-work-with-claude/
- How to Expose a REST API to Claude Desktop: https://usepaso.dev/blog/expose-rest-api-to-claude-desktop/
- MCP Server Without Writing Code: https://usepaso.dev/blog/mcp-server-without-writing-code/
- Why We Built paso: https://usepaso.dev/blog/why-we-built-usepaso/
- OpenAPI to MCP in 60 Seconds: https://usepaso.dev/blog/openapi-to-mcp-in-60-seconds/
- Five Ways to Test Before You Ship: https://usepaso.dev/blog/five-ways-to-test-before-you-ship/
- paso Works the Same in Python: https://usepaso.dev/blog/paso-works-the-same-in-python/

## Links

- https://usepaso.dev
- https://github.com/5h1vmani/usepaso
- https://www.npmjs.com/package/usepaso
- https://pypi.org/project/usepaso/