# paso — llms.txt
# For AI crawlers and language models. See https://llmstxt.org

> paso is an open-source MCP server generator. Developers declare their API's capabilities in a YAML file (usepaso.yaml), and paso generates a live MCP server from that declaration. AI agents connect to the MCP server and interact with the API. 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: Yes — no cloud dependency, no SaaS
- What it generates: A live MCP server (not static files)
- Dual SDK: Node.js (TypeScript) and Python with identical CLI and output

## What It Does

paso solves the protocol integration problem in AI agent infrastructure. Instead of manually writing MCP server code, developers write a single YAML declaration describing their API's capabilities. paso generates a live MCP server that handles protocol compliance, request routing, auth forwarding, input validation, and error handling.

## Core Concepts

- **Declaration:** A YAML file (usepaso.yaml) describing an API's capabilities, inputs, permissions, and constraints
- **MCP Server:** A live server generated from the declaration that AI agents connect to via the Model Context Protocol
- **Permissions:** Capability-level access control with read/write/admin tiers, consent_required for destructive actions, and a forbidden list
- **Constraints:** Rate limits (max_per_hour), pagination limits (max_per_request), value caps (max_value), and field dependencies (requires_field)
- **OpenAPI Import:** Generate a declaration from an existing OpenAPI spec with --from-openapi

## CLI Commands

- usepaso init — Scaffold a new declaration (flags: --name, --from-openapi)
- usepaso validate — Check declaration for errors (flags: --strict, --json)
- usepaso inspect — Preview what MCP tools will be generated (flags: --json)
- usepaso test — Test capabilities with real HTTP requests (flags: --all, --dry-run, --verbose, --timeout, -f)
- usepaso serve — Start an MCP server from the declaration (flags: --watch, --strict, --env)
- usepaso doctor — Diagnose setup issues (flags: --env); runs 6 checks: file exists, YAML parses, validation passes, auth token set, base URL reachable, capability smoke test
- usepaso connect — Write MCP client config automatically (clients: claude-desktop, cursor, vscode, windsurf; flags: --force)
- usepaso disconnect — Remove MCP client config entry (clients: claude-desktop, cursor, vscode, windsurf)
- usepaso completion — Generate shell completions (flags: --shell bash|zsh|fish)
- usepaso version — Print version

## Supported MCP Clients

paso generates config for four MCP clients via `usepaso connect`:
- Claude Desktop: global config at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
- Cursor: project-local at .cursor/mcp.json
- VS Code: project-local at .vscode/mcp.json (uses `servers` key, not `mcpServers`)
- Windsurf: global config at ~/.codeium/windsurf/mcp_config.json

For headless/untrusted environments (CI, automated agents), use `usepaso serve --strict` to enforce consent gates at the server level.

## Programmatic API

Both SDKs export: parseFile, parseString, validate, parseAndValidate, parseFileAndValidate, generateMcpServer, buildRequest, executeRequest, formatError, generateFromOpenApi (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/
- VS Code Setup: https://usepaso.dev/docs/guides/vscode/
- Windsurf Setup: https://usepaso.dev/docs/guides/windsurf/
- 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 Posts

- Stop Editing JSON by Hand (usepaso connect): https://usepaso.dev/blog/usepaso-connect/
- Connect GitHub to VS Code Copilot: https://usepaso.dev/blog/connect-github-to-vs-code/
- Connect Twilio to Windsurf: https://usepaso.dev/blog/connect-twilio-to-windsurf/
- MCP Servers for Agents You Don't Trust (--strict): https://usepaso.dev/blog/mcp-servers-for-untrusted-agents/
- Connect Stripe to Claude Desktop: https://usepaso.dev/blog/connect-stripe-to-claude-desktop/
- 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/
- OpenAPI to MCP in 60 Seconds: https://usepaso.dev/blog/openapi-to-mcp-in-60-seconds/
- What Happens When an Agent Calls DELETE (permission boundaries): https://usepaso.dev/blog/what-happens-when-an-agent-calls-delete/
- What Is a paso Declaration: https://usepaso.dev/blog/what-is-a-paso-declaration/
- The Complete Guide to MCP Servers: https://usepaso.dev/blog/the-complete-guide-to-mcp-servers/
- Five Ways to Test Before You Ship: https://usepaso.dev/blog/five-ways-to-test-before-you-ship/
- paso vs Writing MCP Servers by Hand: https://usepaso.dev/blog/paso-vs-writing-mcp-servers-by-hand/
- Common MCP Server Errors: https://usepaso.dev/blog/common-mcp-server-errors/
- MCP Server Performance: https://usepaso.dev/blog/mcp-server-performance/
- MCP vs REST vs GraphQL: https://usepaso.dev/blog/mcp-vs-rest-vs-graphql/
- paso Works the Same in Python: https://usepaso.dev/blog/paso-works-the-same-in-python/
- Why We Built paso: https://usepaso.dev/blog/why-we-built-usepaso/

## Links

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