Swagger MCP connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. 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

   Node.js

   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)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "swaggermcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Swagger MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="swaggermcp_swagger_list_organizations",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

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

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.

NameTypeRequiredDescription

apiNamestringrequiredAPI name

ownerstringrequiredAPI owner (organization or user, case-sensitive)

promptstringrequiredThe prompt describing the desired API functionality (e.g., 'Create a RESTful API for managing a pet store with endpoints for pets, orders, and inventory')

specTypestringoptionalSpecification 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.

NameTypeRequiredDescription

apiNamestringrequiredAPI name

definitionstringrequiredAPI 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.

ownerstringrequiredOrganization 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.

NameTypeRequiredDescription

subdomainstringrequiredThe portal subdomain - used in the portal URL (e.g., 'myportal' for myportal.example.com). Must be unique, lowercase, 3-20 characters, alphanumeric with hyphens

swaggerHubOrganizationIdstringrequiredThe corresponding SwaggerHub organization UUID - required for portal creation. This links the portal to your SwaggerHub organization

credentialsEnabledbooleanoptionalWhether authentication credentials are enabled for accessing the portal. When true, users can authenticate to access private content. Defaults to true

namestringoptionalThe display name for the portal - shown to users and in branding (3-40 characters)

offlinebooleanoptionalIf true, the portal will not be visible to customers - useful for development/staging environments. Defaults to false

openapiRendererstringoptionalOpenAPI renderer type: 'SWAGGER_UI' (Swagger UI), 'ELEMENTS' (Stoplight Elements), or 'TOGGLE' (allows switching between both with Elements as default). Defaults to 'TOGGLE'

pageContentFormatstringoptionalFormat for page content rendering - determines how documentation pages are processed: 'HTML', 'MARKDOWN', or 'BOTH'. Defaults to 'HTML'

routingstringoptionalRouting 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.

NameTypeRequiredDescription

namestringrequiredProduct display name - will be shown to users in the portal navigation and product listings (3-40 characters)

portalIdstringrequiredPortal UUID or subdomain - unique identifier for the portal instance

slugstringrequiredURL-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

typestringrequiredProduct creation type - 'new' to create from scratch or 'copy' to duplicate an existing product

descriptionstringoptionalProduct description - explains what the API/product does, shown in product listings and cards (max 110 characters)

hiddenbooleanoptionalWhether the product is hidden from the portal landing page navigation menus - useful for internal or draft products

productIdstringoptionalSource product UUID to copy from - required when type is 'copy', specifies which existing product to duplicate. Omit when type is 'new'

publicbooleanoptionalWhether 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.

NameTypeRequiredDescription

ordernumberrequiredOrder position of the table of contents item within its parent section or item

sectionIdstringrequiredSection ID - unique identifier for the section within the product

slugstringrequiredURL-friendly identifier for the table of contents item - must be unique within the section (3-22 characters, lowercase, alphanumeric with hyphens/underscores/dots)

titlestringrequiredTitle of the table of contents item - will be displayed in navigation (3-40 characters)

typestringrequiredType of table of contents creation - 'new' to create from scratch or 'copy' to duplicate an existing one

contentobjectoptionalContent configuration for the table of contents item

parentIdstringoptionalParent 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.

NameTypeRequiredDescription

productIdstringrequiredProduct 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.

NameTypeRequiredDescription

tableOfContentsIdstringrequiredThe table of contents UUID, or identifier in the format 'portal-subdomain:product-slug:section-slug:table-of-contents-slug'

recursivebooleanoptionalFlag 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.

NameTypeRequiredDescription

apistringrequiredAPI name (case-sensitive)

ownerstringrequiredAPI owner (organization or user, case-sensitive)

versionstringrequiredVersion identifier

flattenbooleanoptionalSet to true to create models from inline schemas in OpenAPI definition (default false)

resolvedbooleanoptionalSet 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.

NameTypeRequiredDescription

documentIdstringrequiredDocument 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.

NameTypeRequiredDescription

portalIdstringrequiredPortal 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.

NameTypeRequiredDescription

productIdstringrequiredProduct 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.

NameTypeRequiredDescription

orderstringoptionalSort order

pagenumberoptional0-based index of the page to return

pageSizenumberoptionalNumber of results per page to return

qstringoptionalSearch organizations by partial or full name (case-insensitive)

sortBystringoptionalThe 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.

NameTypeRequiredDescription

productIdstringrequiredProduct UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product

embedarrayoptionalList of related entities to embed in the response - e.g., ['tableOfContents', 'tableOfContents.swaggerhubApi'] to include table of contents and SwaggerHub API details

pagenumberoptionalPage number for paginated results - specifies which page of results to retrieve (default is 1)

sizenumberoptionalNumber 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.

NameTypeRequiredDescription

portalIdstringrequiredPortal 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.

NameTypeRequiredDescription

sectionIdstringrequiredSection ID - unique identifier for the section within the product

embedarrayoptionalList of related entities to embed in the response - e.g., ['swaggerhubApi'] to include SwaggerHub API details

pagenumberoptionalPage number for paginated results - specifies which page of results to retrieve (default is 1)

sizenumberoptionalNumber 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.

NameTypeRequiredDescription

productIdstringrequiredProduct UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product

previewbooleanoptionalWhether 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.

NameTypeRequiredDescription

definitionstringrequiredAPI definition content (OpenAPI/AsyncAPI specification in JSON or YAML format) to scan for standardization errors

orgNamestringrequiredThe 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.

NameTypeRequiredDescription

limitnumberoptionalNumber of results per page (1-100, default 20)

offsetnumberoptionalOffset for pagination (0-based, default 0)

orderstringoptionalSort order - ASC or DESC (default ASC)

ownerstringoptionalFilter APIs by owner (organization or user)

querystringoptionalSearch query to filter APIs by name, description, or content

sortstringoptionalSort field - NAME, UPDATED, or CREATED (default NAME)

specTypestringoptionalFilter by specification type - API or DOMAIN (default all types)

statestringoptionalFilter APIs by publication state - ALL (default), PUBLISHED, or UNPUBLISHED

tagstringoptionalFilter 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.

NameTypeRequiredDescription

apistringrequiredAPI name (case-sensitive)

ownerstringrequiredAPI owner (organization or user, case-sensitive)

versionstringrequiredVersion identifier

newVersionstringoptionalThe 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.

NameTypeRequiredDescription

documentIdstringrequiredDocument UUID - unique identifier for the document

contentstringoptionalThe document content to update (HTML or Markdown based on document type)

sourcestringoptionalSource of the document content - 'internal' allows to edit content in both UI and API, 'external' enables editing only via API.

typestringoptionalContent 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.

NameTypeRequiredDescription

portalIdstringrequiredPortal UUID or subdomain - unique identifier for the portal instance

credentialsEnabledbooleanoptionalEnable/disable authentication credentials for portal access - controls whether users can authenticate to view private content

customDomainbooleanoptionalEnable/disable custom domain for the portal - allows using your own domain instead of the default subdomain

gtmKeystringoptionalGoogle Tag Manager key for analytics tracking - format: GTM-XXXXXX (max 25 characters)

namestringoptionalUpdate the portal display name - shown to users and in branding (3-40 characters)

offlinebooleanoptionalSet portal visibility - true hides portal from customers (useful for maintenance or development)

openapiRendererstringoptionalChange OpenAPI renderer: 'SWAGGER_UI' (Swagger UI), 'ELEMENTS' (Stoplight Elements), or 'TOGGLE' (switch between both)

pageContentFormatstringoptionalUpdate page content format for documentation rendering: 'HTML', 'MARKDOWN', or 'BOTH'

routingstringoptionalUpdate routing strategy - 'browser' for client-side routing or 'proxy' for server-side routing

subdomainstringoptionalUpdate 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.

NameTypeRequiredDescription

productIdstringrequiredProduct UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product

descriptionstringoptionalUpdate product description - explains the API/product functionality, shown in listings (max 110 characters)

hiddenbooleanoptionalChange navigation visibility - true hides from portal landing page menus while keeping the product accessible via direct links

namestringoptionalUpdate product display name - changes how it appears to users in navigation and listings (3-40 characters)

publicbooleanoptionalChange product visibility - true makes it publicly accessible to all visitors, false restricts to authenticated users with roles

slugstringoptionalUpdate URL-friendly identifier - must remain unique within the portal, affects product URLs (3-22 characters, lowercase, alphanumeric with hyphens/underscores/dots)