Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Swagger MCP connector

OAuth 2.1/DCR Developer ToolsProductivity

Connect to Swagger MCP. Create and manage APIs, developer portals, and documentation in SwaggerHub from AI workflows.

Swagger MCP connector

  1. Install the SDK

    Section titled “Install the SDK”
    Terminal window
    npm install @scalekit-sdk/node

    Full SDK reference: Node.js | Python

  2. Set your credentials

    Section titled “Set your credentials”

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Authorize and make your first call

    Section titled “Authorize and make your first call”
    quickstart.ts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENV_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'swaggermcp'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Swagger MCP:', link)
    process.stdout.write('Press Enter after authorizing...')
    await new Promise(r => process.stdin.once('data', r))
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'swaggermcp_swagger_list_organizations',
      toolInput: {},
    })
    console.log(result)

What you can do

Section titled “What you can do”

Connect this agent connector to let your agent:

  • Update swagger — Update the settings of an existing product within a portal
  • Api swagger standardize — Standardize and fix an API definition using AI to comply with the organization’s governance rules
  • Search swagger — Search for APIs and domains in the SwaggerHub registry with optional filters
  • Standardization swagger scan api — Run a standardization scan on an API definition against the organization’s governance rules
  • Product swagger publish portal — Publish a portal product to make its content live, or publish as a preview
  • List swagger — List table of contents entries for a section within a portal product

Tool list

Section titled “Tool list”

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

swaggermcp_swagger_create_api_from_prompt # Generate and save a new API definition in SwaggerHub using SmartBear AI from a natural language prompt. 4 params

Generate and save a new API definition in SwaggerHub using SmartBear AI from a natural language prompt.

Name Type Required Description
apiName string required API name
owner string required API owner (organization or user, case-sensitive)
prompt string required The prompt describing the desired API functionality (e.g., 'Create a RESTful API for managing a pet store with endpoints for pets, orders, and inventory')
specType string optional Specification type for the generated API definition. Use: 'openapi20' for OpenAPI 2.0, 'openapi30x' for OpenAPI 3.0.x (default), 'openapi31x' for OpenAPI 3.1.x, 'asyncapi2xx' for AsyncAPI 2.x, 'asyncapi30x' for AsyncAPI 3.0.x
swaggermcp_swagger_create_or_update_api # Create a new API or update an existing API definition in the SwaggerHub registry. 3 params

Create a new API or update an existing API definition in the SwaggerHub registry.

Name Type Required Description
apiName string required API name
definition string required API definition content (OpenAPI/AsyncAPI specification in JSON or YAML format). Format is automatically detected. API is created with fixed values: version 1.0.0, private visibility, automock disabled, and no project assignment.
owner string required Organization name (owner of the API)
swaggermcp_swagger_create_portal # Create a new developer portal in SwaggerHub. 8 params

Create a new developer portal in SwaggerHub.

Name Type Required Description
subdomain string required The portal subdomain - used in the portal URL (e.g., 'myportal' for myportal.example.com). Must be unique, lowercase, 3-20 characters, alphanumeric with hyphens
swaggerHubOrganizationId string required The corresponding SwaggerHub organization UUID - required for portal creation. This links the portal to your SwaggerHub organization
credentialsEnabled boolean optional Whether authentication credentials are enabled for accessing the portal. When true, users can authenticate to access private content. Defaults to true
name string optional The display name for the portal - shown to users and in branding (3-40 characters)
offline boolean optional If true, the portal will not be visible to customers - useful for development/staging environments. Defaults to false
openapiRenderer string optional OpenAPI renderer type: 'SWAGGER_UI' (Swagger UI), 'ELEMENTS' (Stoplight Elements), or 'TOGGLE' (allows switching between both with Elements as default). Defaults to 'TOGGLE'
pageContentFormat string optional Format for page content rendering - determines how documentation pages are processed: 'HTML', 'MARKDOWN', or 'BOTH'. Defaults to 'HTML'
routing string optional Routing strategy for the portal - either 'browser' (client-side routing) or 'proxy' (server-side routing). Defaults to 'browser'
swaggermcp_swagger_create_portal_product # Create a new product within a portal to group and expose API documentation. 8 params

Create a new product within a portal to group and expose API documentation.

Name Type Required Description
name string required Product display name - will be shown to users in the portal navigation and product listings (3-40 characters)
portalId string required Portal UUID or subdomain - unique identifier for the portal instance
slug string required URL-friendly identifier for the product - must be unique within the portal, used in URLs (e.g., 'my-api' becomes /my-api). 3-22 characters, lowercase, alphanumeric with hyphens, underscores, or dots
type string required Product creation type - 'new' to create from scratch or 'copy' to duplicate an existing product
description string optional Product description - explains what the API/product does, shown in product listings and cards (max 110 characters)
hidden boolean optional Whether the product is hidden from the portal landing page navigation menus - useful for internal or draft products
productId string optional Source product UUID to copy from - required when type is 'copy', specifies which existing product to duplicate. Omit when type is 'new'
public boolean optional Whether the product is publicly visible to all portal visitors - false means only authenticated users with appropriate roles can access it
swaggermcp_swagger_create_table_of_contents # Add a new entry to the table of contents for a portal product section. 7 params

Add a new entry to the table of contents for a portal product section.

Name Type Required Description
order number required Order position of the table of contents item within its parent section or item
sectionId string required Section ID - unique identifier for the section within the product
slug string required URL-friendly identifier for the table of contents item - must be unique within the section (3-22 characters, lowercase, alphanumeric with hyphens/underscores/dots)
title string required Title of the table of contents item - will be displayed in navigation (3-40 characters)
type string required Type of table of contents creation - 'new' to create from scratch or 'copy' to duplicate an existing one
content object optional Content configuration for the table of contents item
parentId string optional Parent table of contents item ID - null for top-level items, or ID of parent item for nested structure
swaggermcp_swagger_delete_portal_product # Delete a product from a portal by product ID. 1 param

Delete a product from a portal by product ID.

Name Type Required Description
productId string required Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product
swaggermcp_swagger_delete_table_of_contents # Remove a table of contents entry from a portal product section. 2 params

Remove a table of contents entry from a portal product section.

Name Type Required Description
tableOfContentsId string required The table of contents UUID, or identifier in the format 'portal-subdomain:product-slug:section-slug:table-of-contents-slug'
recursive boolean optional Flag to include all the nested tables of contents (default: false)
swaggermcp_swagger_get_api_definition # Fetch an API definition from the SwaggerHub registry by owner, API name, and version. 5 params

Fetch an API definition from the SwaggerHub registry by owner, API name, and version.

Name Type Required Description
api string required API name (case-sensitive)
owner string required API owner (organization or user, case-sensitive)
version string required Version identifier
flatten boolean optional Set to true to create models from inline schemas in OpenAPI definition (default false)
resolved boolean optional Set to true to get the resolved version with all external $refs included (default false)
swaggermcp_swagger_get_document # Retrieve the content and metadata of a portal document by its ID. 1 param

Retrieve the content and metadata of a portal document by its ID.

Name Type Required Description
documentId string required Document UUID - unique identifier for the document
swaggermcp_swagger_get_portal # Retrieve configuration and details for a specific portal by ID. 1 param

Retrieve configuration and details for a specific portal by ID.

Name Type Required Description
portalId string required Portal UUID or subdomain - unique identifier for the portal instance
swaggermcp_swagger_get_portal_product # Retrieve details for a specific product within a portal. 1 param

Retrieve details for a specific product within a portal.

Name Type Required Description
productId string required Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product
swaggermcp_swagger_list_organizations # List organizations the authenticated user belongs to, with optional search and pagination. 5 params

List organizations the authenticated user belongs to, with optional search and pagination.

Name Type Required Description
order string optional Sort order
page number optional 0-based index of the page to return
pageSize number optional Number of results per page to return
q string optional Search organizations by partial or full name (case-insensitive)
sortBy string optional The property to sort the results by
swaggermcp_swagger_list_portal_product_sections # List sections within a portal product, with optional pagination and embedded data. 4 params

List sections within a portal product, with optional pagination and embedded data.

Name Type Required Description
productId string required Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product
embed array optional List of related entities to embed in the response - e.g., ['tableOfContents', 'tableOfContents.swaggerhubApi'] to include table of contents and SwaggerHub API details
page number optional Page number for paginated results - specifies which page of results to retrieve (default is 1)
size number optional Number of items per page for pagination - controls how many results are returned per page (default is 20)
swaggermcp_swagger_list_portal_products # List all products within a specific portal. 1 param

List all products within a specific portal.

Name Type Required Description
portalId string required Portal UUID or subdomain - unique identifier for the portal instance
swaggermcp_swagger_list_portals # List all portals the user has access to. 0 params

List all portals the user has access to.

swaggermcp_swagger_list_table_of_contents # List table of contents entries for a section within a portal product. 4 params

List table of contents entries for a section within a portal product.

Name Type Required Description
sectionId string required Section ID - unique identifier for the section within the product
embed array optional List of related entities to embed in the response - e.g., ['swaggerhubApi'] to include SwaggerHub API details
page number optional Page number for paginated results - specifies which page of results to retrieve (default is 1)
size number optional Number of items per page for pagination - controls how many results are returned per page (default is 20)
swaggermcp_swagger_publish_portal_product # Publish a portal product to make its content live, or publish as a preview. 2 params

Publish a portal product to make its content live, or publish as a preview.

Name Type Required Description
productId string required Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product
preview boolean optional Whether to publish as preview (true) or live (false). Preview allows testing before going live. Defaults to false (live publication)
swaggermcp_swagger_scan_api_standardization # Run a standardization scan on an API definition against the organization's governance rules. 2 params

Run a standardization scan on an API definition against the organization's governance rules.

Name Type Required Description
definition string required API definition content (OpenAPI/AsyncAPI specification in JSON or YAML format) to scan for standardization errors
orgName string required The organization name to use for standardization rules
swaggermcp_swagger_search_apis_and_domains # Search for APIs and domains in the SwaggerHub registry with optional filters. 9 params

Search for APIs and domains in the SwaggerHub registry with optional filters.

Name Type Required Description
limit number optional Number of results per page (1-100, default 20)
offset number optional Offset for pagination (0-based, default 0)
order string optional Sort order - ASC or DESC (default ASC)
owner string optional Filter APIs by owner (organization or user)
query string optional Search query to filter APIs by name, description, or content
sort string optional Sort field - NAME, UPDATED, or CREATED (default NAME)
specType string optional Filter by specification type - API or DOMAIN (default all types)
state string optional Filter APIs by publication state - ALL (default), PUBLISHED, or UNPUBLISHED
tag string optional Filter APIs by tag
swaggermcp_swagger_standardize_api # Standardize and fix an API definition using AI to comply with the organization's governance rules. 4 params

Standardize and fix an API definition using AI to comply with the organization's governance rules.

Name Type Required Description
api string required API name (case-sensitive)
owner string required API owner (organization or user, case-sensitive)
version string required Version identifier
newVersion string optional The version to save the fixed definition as (e.g. '1.0.1'). Omitting this will overwrite the current version — prefer providing a patch bump (e.g. '1.0.0' → '1.0.1') unless the user specifies otherwise.
swaggermcp_swagger_update_document # Update the content or source URL of an existing portal document. 4 params

Update the content or source URL of an existing portal document.

Name Type Required Description
documentId string required Document UUID - unique identifier for the document
content string optional The document content to update (HTML or Markdown based on document type)
source string optional Source of the document content - 'internal' allows to edit content in both UI and API, 'external' enables editing only via API.
type string optional Content type - 'html' for HTML content or 'markdown' for Markdown content
swaggermcp_swagger_update_portal # Update the configuration of an existing portal. 10 params

Update the configuration of an existing portal.

Name Type Required Description
portalId string required Portal UUID or subdomain - unique identifier for the portal instance
credentialsEnabled boolean optional Enable/disable authentication credentials for portal access - controls whether users can authenticate to view private content
customDomain boolean optional Enable/disable custom domain for the portal - allows using your own domain instead of the default subdomain
gtmKey string optional Google Tag Manager key for analytics tracking - format: GTM-XXXXXX (max 25 characters)
name string optional Update the portal display name - shown to users and in branding (3-40 characters)
offline boolean optional Set portal visibility - true hides portal from customers (useful for maintenance or development)
openapiRenderer string optional Change OpenAPI renderer: 'SWAGGER_UI' (Swagger UI), 'ELEMENTS' (Stoplight Elements), or 'TOGGLE' (switch between both)
pageContentFormat string optional Update page content format for documentation rendering: 'HTML', 'MARKDOWN', or 'BOTH'
routing string optional Update routing strategy - 'browser' for client-side routing or 'proxy' for server-side routing
subdomain string optional Update the portal subdomain - changes the portal URL. Must remain unique across all portals (3-20 characters, lowercase, alphanumeric with hyphens)
swaggermcp_swagger_update_portal_product # Update the settings of an existing product within a portal. 6 params

Update the settings of an existing product within a portal.

Name Type Required Description
productId string required Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product
description string optional Update product description - explains the API/product functionality, shown in listings (max 110 characters)
hidden boolean optional Change navigation visibility - true hides from portal landing page menus while keeping the product accessible via direct links
name string optional Update product display name - changes how it appears to users in navigation and listings (3-40 characters)
public boolean optional Change product visibility - true makes it publicly accessible to all visitors, false restricts to authenticated users with roles
slug string optional Update URL-friendly identifier - must remain unique within the portal, affects product URLs (3-22 characters, lowercase, alphanumeric with hyphens/underscores/dots)