# SwaggerHub MCP

> SwaggerHub MCP connects your AI client directly to an entire organization's API catalog. Read, validate, and retrieve full OpenAPI specifications, shared domain definitions, and project structures without leaving your chat window.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** openapi, api-design, documentation, api-lifecycle, rest-api

## Description

This connector turns your LLM into a technical architect that handles enterprise API complexity. You can query thousands of APIs across your whole company—from finding an entire roster using `list_apis` to pulling the exact JSON OpenAPI schema for a specific version via `get_api_version_spec`. It lets you investigate shared, reusable definitions by listing domains and fetching details with `list_domains`, so you never have to hunt through multiple graphical interfaces. If your team needs to map out project boundaries or check CI/CD sync status across systems like GitHub or AWS, this MCP handles it all. This makes context switching a thing of the past. By connecting through Vinkius, you get instant access to this critical layer of API governance, right where you're working with your agent.

## Tools

### get_api_details
Retrieves basic metadata about any specified SwaggerHub API definition.

### get_api_version_spec
Pulls the complete, structured OpenAPI JSON specification for a specific version of an API.

### get_domain_details
Retrieves detailed metadata on any reusable component domain within your organization's APIs.

### get_project_details
Gets comprehensive information about a specific API development project structure.

### list_apis
Lists every single API definition owned by your account or organization in one command.

### list_domains
Lists all shared, reusable component definitions (domains) used across multiple APIs.

### list_api_integrations
Checks and lists every connected CI/CD system (like AWS or GitHub) for a given API definition.

### list_projects
Lists all major development projects active within your SwaggerHub organization.

### list_api_templates
Shows you a catalog of available starting templates for new API designs.

### search_apis
Searches all public APIs by keyword to find definitions outside your direct ownership.

## Prompt Examples

**Prompt:** 
```
Search for public API specifications related to 'payment gateway' on SwaggerHub.
```

**Response:** 
```
Accessing public registries ('search_apis')...
Found 3 matches for 'payment gateway':
- 'AcmeCorp-Payments' (Version: v1.2.0)
- 'OpenPay-Gateway' (Version: v3.0.0)
- 'SecureTx-API' (Version: v1.0.1)

Let me know if you want me to fetch the OpenAPI specs for any of these results natively.
```

**Prompt:** 
```
List all active projects in our SwaggerHub organization.
```

**Response:** 
```
Mapping team clusters ('list_projects')...
I found 2 core organizational projects:
1. 'Billing-Infrastructure' (4 underlying APIs)
2. 'User-Authentication-Systems' (2 shared domains and 1 API configuration)
```

**Prompt:** 
```
Ensure that the 'Acme-Billing' API has AWS API Gateway integration synced currently.
```

**Response:** 
```
Interrogating pipeline bounds ('list_api_integrations')...
The specified API 'Acme-Billing' v1.0.0 currently returns 1 active integration:
- Type: AWS API Gateway Sync
- Status: Synced & Configured Successfully
- Last Run: 25 minutes ago.
```

## Capabilities

### Audit and locate APIs
List every existing API definition or search for a public API using keywords across the entire organization.

### Retrieve technical specifications
Pull specific, versioned OpenAPI JSON schemas for immediate use in coding or validation.

### Map reusable components
Identify and get metadata on shared domain definitions that multiple APIs depend on.

### View organizational structure
List all active projects or check the integration status of a project's deployment pipelines.

## Use Cases

### A new engineer needs to know what APIs are available.
Instead of asking a colleague, the agent runs `list_apis` and immediately provides the complete list of all corporate services. The engineer can then use `get_api_details` on any service name found.

### A developer needs to verify if an API is ready for production deployment.
The agent runs `list_api_integrations` and confirms that the 'BillingAPI' has a successful sync record with AWS. If the status is stale, the engineer knows exactly what step must happen before coding.

### A technical writer needs to document all reusable components.
The agent runs `list_domains` and gathers every shared component name. The writer can then use `get_domain_details` on each one to write accurate, structured documentation.

### A team is starting a new service and needs architectural guidance.
The agent first runs `list_projects` to see existing standards. It can then pull the OpenAPI schema from an existing project using `get_api_version_spec`, ensuring the new design adheres to company policy.

## Benefits

- You stop manually navigating through web portals. With this MCP, you can use `list_apis` to get a full roster of every API definition in your organization instantly.
- No more copy-pasting boilerplate code. When you need the raw structure, calling `get_api_version_spec` pulls the exact OpenAPI JSON schema ready for consumption.
- You gain visibility into reusable parts. If an API uses a shared component, running `list_domains` shows you that dependency and fetching details via `get_domain_details` gives context on how it works.
- Deployment status is always visible. You can run `list_api_integrations` to audit if your APIs are correctly synced with AWS or GitHub before a release, eliminating manual checks.
- Project mapping gets simple. Use `list_projects` and `get_project_details` to map out complex team structures without guessing which repository owns which service.

## How It Works

The bottom line is you get programmatic access to every part of your API design lifecycle without clicking a single button in a web browser.

1. First, append the SwaggerHub MCP framework to your AI client environment.
2. Next, configure access by mapping your organizational API key into your credentials setup.
3. Then, instruct your agent directly: "What is the OpenAPI spec for 'BillingAPI' version 2.0.0 and what shared domains does it need?"

## Frequently Asked Questions

**How do I find all APIs my organization owns using SwaggerHub MCP?**
You run the `list_apis` tool. This immediately retrieves every API definition associated with your account, giving you a complete inventory in one step.

**Can SwaggerHub MCP help me see what APIs are available publicly?**
Yes, use the `search_apis` tool. It searches all public registries by keyword so you can find external specifications without leaving your chat client.

**What is the difference between list_domains and get_domain_details using SwaggerHub MCP?**
`list_domains` shows a full catalog of every reusable component in your organization. `get_domain_details` takes one specific domain name and gives you its full metadata.

**Does the SwaggerHub MCP only work with existing APIs?**
No. You can use `list_api_templates` to see starting points for new services, giving you a head start on your API design process.

**How do I check if an API is integrated with AWS using SwaggerHub MCP?**
Run the `list_api_integrations` tool. It reports the status and type of connection for any specified API, confirming your deployment readiness.