Menu

OpenAPI Import

Generate an MCP server declaration from an existing OpenAPI spec.

Can I generate an MCP server from an OpenAPI spec?

Yes. If you have an OpenAPI 3.x spec, paso converts it into a usepaso.yaml declaration. One command. File or URL.

usepaso init --from-openapi ./openapi.json
usepaso init --from-openapi https://api.example.com/openapi.json

Supports JSON and YAML OpenAPI 3.x specs.

What Gets Generated

The import process extracts:

  • Service name and description from the info section
  • Base URL from servers[0].url
  • Auth type from security schemes
  • Capabilities from each path + method combination
  • Inputs from path parameters, query parameters, and request body
  • Descriptions from operation summaries

Example output:

version: "1.0"

service:
  name: Petstore
  description: A sample API for managing pets
  base_url: https://api.petstore.com/v1
  auth:
    type: bearer

capabilities:
  - name: list_pets
    description: List all pets
    method: GET
    path: /pets
    permission: read
    inputs:
      limit:
        type: integer
        description: How many items to return
        in: query
      status:
        type: string
        description: Filter by status
        in: query

  - name: create_pet
    description: Create a new pet
    method: POST
    path: /pets
    permission: write
    inputs:
      name:
        type: string
        required: true
        description: Pet name
      species:
        type: string
        required: true
        description: Pet species

The CLI prints a summary after generation:

Generated usepaso.yaml from ./openapi.json
  Service:      Petstore
  Capabilities: 8 (5 read, 2 write, 1 admin)
  Auth:         bearer

Curate Your Declaration

The auto-generated declaration is a starting point. Review and customize it.

Remove Capabilities

Delete capabilities you don’t want agents to use.

Adjust Permissions

Set permission tiers based on risk:

- name: delete_pet
  description: Delete a pet permanently
  method: DELETE
  path: /pets/{pet_id}
  permission: admin
  consent_required: true
  inputs:
    pet_id:
      type: string
      required: true
      description: The pet ID
      in: path

Add Constraints

Limit API usage:

constraints:
  - max_per_hour: 100
    description: Deletion is rate-limited

Add Forbidden Capabilities

Block specific capabilities from being exposed:

permissions:
  read:
    - list_pets
    - get_pet
  write:
    - create_pet
  forbidden:
    - delete_pet

Cap on Generated Capabilities

UsePaso caps at 20 capabilities per import to keep declarations manageable. If your OpenAPI spec has more operations, the CLI will note how many were found versus generated. Edit usepaso.yaml to add more manually, or remove ones you don’t need and re-import.

Validate After Import

Always validate after importing:

usepaso validate

The generated declaration handles common OpenAPI patterns but not every edge case. Fix any validation errors, set appropriate permissions, and review before serving.

Your OpenAPI spec is now a paso declaration.

Review it, set permissions, and serve.

Next, you might want to:

From the blog: