OpenAPI to MCP in 60 Seconds

Tutorials 5h1vmani 2 min
On this page

You have an OpenAPI spec. You want Claude to use your API. Here’s the entire process.

Start with your spec

Any OpenAPI 3.x spec works. JSON or YAML. Local file or URL.

usepaso init --from-openapi ./openapi.json

Or from a URL:

usepaso init --from-openapi https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json

What happens

paso reads the spec and generates a usepaso.yaml declaration. It extracts:

  • Service name and description from info
  • Base URL from servers[0].url
  • Auth type from security schemes
  • One capability per operation (path + method)
  • Inputs from path params, query params, and request body

The CLI prints what it found:

Generated usepaso.yaml from ./openapi.json
  Service:      Stripe
  Capabilities: 47 (32 read, 12 write, 3 admin)
  Auth:         bearer

Validate

usepaso validate
valid (Stripe, 47 capabilities, 0 regrets)

If validation fails, fix the flagged issues. The OpenAPI converter handles common patterns but not every edge case.

Review and curate

The generated declaration is a starting point. A large API like Stripe has hundreds of endpoints. Agents don’t need all of them. Open usepaso.yaml and:

  1. Remove capabilities you don’t want exposed to agents
  2. Add consent_required: true to write and admin operations
  3. Add constraints (rate limits, max values) where appropriate
  4. Add a permissions section with a forbidden list for sensitive endpoints
permissions:
  read:
    - list_charges
    - get_balance
    - list_customers
  write:
    - create_charge
    - create_refund
  forbidden:
    - delete_customer
    - update_account_settings

Serve

export USEPASO_AUTH_TOKEN="sk_live_your-stripe-key"
usepaso serve
usepaso serving "Stripe" (5 capabilities). Agents welcome.

Connect to Claude Desktop

usepaso connect claude-desktop

paso writes the config for you. Restart Claude. Your API is now agent-accessible.

The whole thing

usepaso init --from-openapi ./openapi.json
usepaso validate
usepaso serve
usepaso connect claude-desktop

Four commands. Your OpenAPI spec is now an MCP server, connected.

If you don’t have an OpenAPI spec, usepaso init creates a template you can fill in manually. Either way, the result is the same: a usepaso.yaml declaration that paso turns into a working server.

Questions

What OpenAPI versions are supported? OpenAPI 3.x (3.0 and 3.1). Swagger 2.0 specs need to be converted first. Tools like swagger2openapi handle this.

What if my spec has hundreds of endpoints? paso imports all of them. The curation step is where you trim to the subset agents need. Most APIs expose 5-15 capabilities to agents, not the full surface.

Does paso handle OAuth scopes from the spec? paso extracts the auth type (bearer, api-key, basic) from security schemes. OAuth scope enforcement happens at the API level, not the MCP layer.

Related:

Read the full OpenAPI import docs.