swagger-mcp MCP Server: Comprehensive Integration for AI Applications

Overview: What is swagger-mcp MCP Server?

swagger-mcp is an innovative tool designed to integrate AI applications with RESTful APIs and tools through Model Context Protocol (MCP). By utilizing the Swagger UI, it extracts the swagger.json file and dynamically generates well-defined MCP tools at runtime. This server facilitates seamless communication between the MCP client and a wide array of backend services, enhancing the flexibility and adaptability of AI workflows.

🔧 Core Features & MCP Capabilities

swagger-mcp leverages the Model Context Protocol (MCP) to provide a standardized framework for integrating backend APIs with various AI clients. Its primary capabilities include:

• Dynamic Tool Generation: It auto-generates tools from Swagger/OpenAPI JSON files, ensuring that both developers and users can quickly access and utilize API data.
• Real-time Communication: Supports Server Sent Events (SSE) mode to enable real-time updates and notifications between the client and server.
• Security Integration: Provides various security methods such as Basic Auth, Bearer Token, and API Key authentication to enhance data security.

⚙️ MCP Architecture & Protocol Implementation

The architecture of swagger-mcp is built around a modular design, ensuring that it can seamlessly integrate with different backend services. It follows the Model Context Protocol (MCP) specifications, which are designed to be universally compatible with various AI applications. The protocol flow can be illustrated through the following Mermaid diagram:

graph TD
    A[AI Application] -->|MCP Client| B[MCP Protocol]
    B --> C[MCP Server]
    C --> D[Data Source/Tool]
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#e8f5e8

Integration with MCP Clients

To ensure compatibility across different AI clients, swagger-mcp supports a wide range of MCP clients. This integration matrix highlights its support for popular AI desktop applications:

MCP Client	Resources	Tools	Prompts
Claude Desktop	✅	✅	✅
Continue	✅	✅	✅
Cursor	❌	✅	❌

🚀 Getting Started with Installation

To get started, simply install the swagger-mcp package using the following command:

go install github.com/hauntingsteps/swagger-mcp@latest

Alternatively, you can run it directly from the terminal with a specified Swagger API URL:

swagger-mcp --specUrl=https://your_swagger_api_docs.json

Configuration Flags

The tool supports several flags and options to customize its behavior. Key ones include:

• --specUrl: Required parameter specifying the Swagger/OpenAPI JSON file URL.
• --sseMode: Run in SSE mode if true. Default is false; otherwise, uses stdio.
• --sseAddr and --sseUrl: Parameters for configuring the SSE server's address and base URL.
• --baseUrl, --security, --basicAuth, --bearerAuth, --apiKeyAuth: Additional options to handle API requests and authentication.

💡 Key Use Cases in AI Workflows

Flow Diagram

The following flow diagram outlines a typical workflow when integrating swagger-mcp with an AI application:

graph TB
    A[Backend Service] -->|MCP Client| B[MCP Protocol]
    B --> C[MCP Server]
    C --> D[Data Source/Tool]
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#e8f5e8

Example Workflow

Here is a step-by-step example of integrating swagger-mcp with an AI application and backend service:

1. Start a Backend Service:

   go install github.com/danishjsheikh/go-backend-demo@latest 
   go-backend-demo
   

2. Run the Ollama Model:

   ollama run llama3.2
   

3. Configure and Run the MCP Client:

   go install github.com/mark3labs/mcphost@latest 
   mcphost -m ollama:llama3.2 --config <.mcp.json_file_path>
   

🔌 Integration with MCP Clients

For compatibility, swagger-mcp supports integration with various MCP clients, as demonstrated in the examples below.

Configuration Example

To integrate swagger-mcp with an .mcp.json configuration file, use this example:

{
  "mcpServers": {
    "swagger_loader": {
      "command": "swagger-mcp",
      "args": ["--specUrl=<swagger/doc.json_url>"]
    }
  }
}

This setup ensures that the MCP client can connect to the backend service and utilize its tools efficiently.

📊 Performance & Compatibility Matrix

The performance of swagger-mcp has been tested with various AI clients, ensuring broad compatibility. Here is a compatibility matrix highlighting supported tools:

Tool	Resources	Tools	Prompts
API Doc Generator	✅	✅	✅
Auto-Completion Tool	✅	❌	✅

🛠️ Advanced Configuration & Security

Security Settings

swagger-mcp supports robust security measures to protect data integrity and confidentiality:

• Basic Auth: Use user:password combinations for basic authentication.
• Bearer Token: Implement token-based authentication using a Bearer token.
• API Key: Manage API keys by specifying header, query or cookie parameters.

You can configure these settings via command-line options as needed.

Security Example

mcphost -m ollama:llama3.2 --config <.mcp.json_file_path> --basicAuth=admin:password --bearerAuth=bearer_token_value --apiKeyAuth=header:token=abc,query:user=foo,cookie:sid=xxx

❓ Frequently Asked Questions (FAQ)

1. What is the difference between --sseMode and --stdio?

   • --sseMode enables Server Sent Events (SSE) mode for real-time updates, while --stdio uses standard input/output streams.

2. Can I change the base URL of API requests?

   • Yes, you can override the base URL using the --baseUrl flag: swagger-mcp --specUrl=https://example.com/swagger.json --baseUrl=http://api.example.com.

3. How do I set up authentication for my AI application?

   • You can choose from Basic Auth, Bearer Token auth, or API Key auth by specifying relevant flags during the setup.

4. What tools are supported in swagger-mcp?

   • swagger-mcp supports a wide range of tools defined in the Swagger/OpenAPI JSON document, including security management and real-time updates.

5. Can I use this with non-Swagger documents?

   • While primarily designed for Swagger/OpenAPI documents, you can adapt it to other formats if necessary by modifying the configuration settings.

👨‍💻 Development & Contribution Guidelines

Contributions are welcome! If you wish to contribute or need help, here are some guidelines:

1. Issue Tracker: Open issues on GitHub to report bugs or suggest features.
2. Code Contributions: Fork the repository and submit pull requests for improvements.
3. Documentation Enhancements: Update existing documentation or add new sections as needed.

Your contributions will significantly improve the usability and functionality of swagger-mcp.

🌐 MCP Ecosystem & Resources

For more detailed resources on the Model Context Protocol (MCP) and related tools, explore these links:

• MCP Documentation
• Model Context Protocol

By leveraging swagger-mcp, developers can build robust AI applications that seamlessly integrate with backend services through a standardized protocol.