usepaso 0.4.1

Make your API agent-ready in minutes. One declaration, every protocol.

paso

The agent-readiness toolkit for APIs.

Declare your API's capabilities once. paso generates the MCP server. No protocol code required.

Self-hosted. Open source. Apache 2.0.

Install

pip install usepaso

Quick Start

# Scaffold a declaration
usepaso init --name "MyService"

# Or generate from an existing OpenAPI spec
usepaso init --from-openapi ./openapi.json

# Check it
usepaso validate

# Preview what MCP tools will be generated
usepaso inspect

# Test a capability (without the consequences)
usepaso test list_issues -p org=acme -p project=web --dry-run

# Start the MCP server
usepaso serve

That's it. Your API is agent-ready.

What You Write

# usepaso.yaml
version: "1.0"

service:
  name: MyService
  description: My API service
  base_url: https://api.example.com
  auth:
    type: bearer

capabilities:
  - name: list_items
    description: List all items
    method: GET
    path: /items
    permission: read

  - name: create_item
    description: Create a new item
    method: POST
    path: /items
    permission: write
    consent_required: true
    inputs:
      name:
        type: string
        required: true
        description: Item name

What paso Does With It

Each capability becomes an MCP tool. When an agent calls it, paso makes the HTTP request to your API with proper auth, parameters, and error handling.

CLI

Command	What it does
usepaso init	Scaffold a usepaso.yaml template (JSONPlaceholder example)
usepaso init --blank	Scaffold a blank template
usepaso init --from-openapi	Generate from an OpenAPI spec
usepaso validate	Check your declaration for errors
usepaso validate --strict	Check for best practices (missing constraints, consent)
usepaso inspect	Preview MCP tools that will be generated
usepaso test <capability>	Test a capability against the live API
usepaso test --dry-run	Same thing, minus the consequences
usepaso test --all --dry-run	Verify all capabilities resolve correctly
usepaso serve	Start an MCP server (stdio)
usepaso serve --strict	Serve with consent gates enforced (two-phase confirmation)
usepaso serve --verbose	Serve with request logging
usepaso connect <client>	Wire this server into an MCP client config (claude-desktop, cursor, vscode, windsurf)
usepaso disconnect <client>	Remove from an MCP client config
usepaso doctor	Check your setup end-to-end
usepaso completion	Output shell completion script (bash, zsh, fish)
usepaso version	Print the version

Programmatic Usage

from usepaso import parse_file, validate

decl = parse_file('usepaso.yaml')
errors = validate(decl)

Connect to MCP Clients

usepaso connect claude-desktop
usepaso connect cursor
usepaso connect vscode
usepaso connect windsurf

Or add manually to your client config:

{
  "mcpServers": {
    "my-service": {
      "command": "usepaso",
      "args": ["serve", "-f", "/path/to/usepaso.yaml"],
      "env": { "USEPASO_AUTH_TOKEN": "your-token" }
    }
  }
}

Links

• Documentation
• Blog
• Changelog
• Spec reference
• Examples
• Node.js SDK

License

Apache 2.0