Skip to content
PipMCP

Import an OpenAPI spec

Supported formats, how imports work, limits, and what to do when an import fails.

An integration in PipMCP represents one API. You create it by importing a definition. Every import produces an immutable version of that integration, with its own operations, schemas, auth schemes and generated tools.

Supported sources

Source source_type Notes
OpenAPI 3.0 / 3.1 by URL openapi_url JSON or YAML. External $refs are resolved.
OpenAPI or Swagger file openapi_upload Upload .json, .yaml or .yml, or paste the content.
Swagger 2.0 openapi_url / openapi_upload Converted to the same internal model as OpenAPI 3.
Postman Collection v2.0 / v2.1 postman Folders become groups; example bodies are used to infer schemas.
GraphQL graphql SDL (.graphql, .gql) or an introspection result. Queries and mutations become operations.
Documentation URL docs_url Experimental. Endpoints are extracted from HTML documentation with AI and always marked for review.
Manual manual Define individual endpoints yourself when there is no spec.

Import from the dashboard

  1. Open Integrations and choose Add API.
  2. Paste a URL, upload a file or paste the definition.
  3. Follow the live progress. PipMCP parses the source, resolves references, maps endpoints to business actions and compiles tools.
  4. When it finishes, review the result (see Tools and mappings) and publish.

Import with the API

curl -X POST https://pipmcp.com/api/v1/integrations \
  -H "Authorization: Bearer pmk_your_token" \
  -H "Content-Type: application/json" \
  -d '{"source_type": "openapi_url", "url": "https://api.example.com/openapi.json", "wait": false}'

With "wait": false the import runs in the background; poll GET /api/v1/integrations/{id} until the version status is review or ready. See Management API.

Limits

  • Maximum source size: 10 MB.
  • Maximum operations per import: 5,000.
  • Up to 25 remote $ref documents and 5 redirects are followed per import.
  • Remote fetches time out after 20 seconds.

How URLs are fetched

URLs are fetched from PipMCP's servers through an outbound guard. Only http and https on ports 80, 443, 8080 and 8443 are allowed, and the host must resolve to a public IP address. Localhost, private ranges (such as 10.0.0.0/8 or 192.168.0.0/16), link-local and cloud metadata addresses are rejected. Every redirect is checked again.

If your spec is only reachable inside your network, download it and upload the file instead. Note that tool calls also need to reach the API itself over the public internet; see Troubleshooting.

Keeping the integration up to date

A new URL import does not refresh on its own. For URL-based sources you can turn on automatic refresh in the integration settings. PipMCP then re-fetches the source periodically (by default every 24 hours) and creates a new version only when the file changed. New versions are not published automatically unless you turn on auto-publish safe changes for the integration; then a version with no breaking changes and nothing to review is published for you. See Versioning.

What gets sent to AI models

Semantic analysis may use an AI model to name tools and classify endpoints. Only the API definition is used: never your credentials, and never live request or response data.

When an import fails

The version shows the error and the stage it failed in. Common causes:

  • The URL returned HTML (a docs page) instead of a spec. Use the raw spec URL, or choose the documentation URL source.
  • The file is not valid JSON or YAML, or is not an OpenAPI, Swagger, Postman or GraphQL document.
  • The host resolves to a private address and was blocked.
  • The source exceeds the size or operation limit.

Fix the source and choose Retry, or import again.