Janus MCP

Janus MCP is a Model Context Protocol server that enables AI assistants to understand and interact with OpenAPI specifications. It provides your AI with deep insight into API structures, making API integration projects faster and more accurate. The server includes token-optimized output formats to reduce costs and improve response efficiency for your AI interactions.

What It Does

Janus MCP transforms how you and your AI assistant work together on projects involving APIs. Instead of manually parsing OpenAPI specifications or struggling to understand complex API structures, your AI can directly query and explore API documentation to provide precise, context-aware assistance.

When working on API integration projects, your AI assistant can:

• Instantly understand the complete structure of any OpenAPI-compliant API
• Provide accurate endpoint information including parameters, request bodies, and response schemas
• Help generate correct API calls with proper data structures
• Explain API relationships and data flows
• Assist with error handling by understanding expected error responses
• Generate comprehensive documentation in markdown or interactive HTML formats

Installation

Add Janus MCP to your AI assistant's configuration:

{
  "mcpServers": {
    "janus": {
      "command": "npx",
      "args": ["janus-mcp"],
      "env": {
        "JANUS_OUTPUT_FORMAT": "compact"
      }
    }
  }
}

The JANUS_OUTPUT_FORMAT environment variable sets the default output format for new sessions. Available formats are compact (default), structured, markdown, and json.

How It Works

Janus MCP creates sessions from OpenAPI specification files (JSON or YAML) or URLs and provides your AI with tools to explore them systematically. Each session maintains the API context and output format preference, allowing for efficient querying without repeatedly parsing large specification files. Your AI can choose from multiple output formats optimized for different use cases and token efficiency.

Your AI assistant can initialize a session with any OpenAPI specification and then:

• List all available endpoints with filtering by tags, HTTP methods, or other criteria
• Get detailed information about specific endpoints including parameters, request schemas, and response formats
• Explore reusable components like data models, security schemes, and error schemas
• Navigate complex APIs with dozens or hundreds of endpoints organized by functional areas
• Understand relationships between endpoints, data models, and business workflows
• Switch between output formats during the session to optimize for readability or token efficiency
• Generate professional documentation with expanded schema details and markdown rendering

Example Workflow

When you're building an application that needs to integrate with a REST API:

1. You provide the OpenAPI specification file or URL to your AI assistant
2. The AI initializes a Janus session and explores the API structure, understanding its scope and organization
3. As you describe what you want to build, the AI can reference exact endpoint details, parameter requirements, and response formats
4. The AI understands complex data relationships and can suggest optimal integration patterns
5. The AI generates accurate integration code with proper error handling, data validation, and security considerations
6. Throughout development, the AI maintains context about the API structure for ongoing assistance

For example, when working with an enterprise compliance API with 88 endpoints across 24 functional areas, your AI can:

• Filter endpoints by tags like "Documents", "Users", or "Audit Logs" to focus on relevant functionality
• Understand that document creation requires specific audit notes and sensitivity levels
• Navigate complex workflows like document approval processes with proper status transitions
• Generate code that handles OAuth2 authentication and encrypted data properly
• Suggest appropriate error handling for different endpoint response patterns

Output Formats

Your AI can work with responses in multiple formats:

Compact: Token-efficient format that reduces response size significantly compared to JSON. Ideal for cost optimization and quick scanning of large endpoint lists.

Structured: Readable text format with clear labels and organization. Balances readability with token efficiency, reducing size slightly compared to JSON.

Markdown: Formatted documentation-style output with headers, code blocks, and emphasis. Excellent for generating API documentation or detailed explanations.

JSON: Full structured data format maintaining complete compatibility with existing integrations and tools that expect JSON responses.

Documentation Generation

Your AI can generate comprehensive API documentation in two formats:

Markdown Documentation: Traditional markdown files with detailed endpoint information, expanded schema definitions, and proper markdown rendering of API descriptions. Ideal for version control, README files, or integration with documentation platforms.

Interactive HTML Documentation: Professional web-based documentation featuring a fixed sidebar navigation, color-coded HTTP methods, expandable schema details, and responsive design. The HTML format includes smooth scrolling navigation, required field indicators, and detailed property tables that show actual field structures instead of just type names.

Both formats automatically parse and render markdown content within API descriptions, endpoint summaries, and parameter documentation. Schema references are expanded inline to show complete object structures with property types, requirements, and descriptions, eliminating the need to cross-reference separate schema sections.

Capabilities

The tools available to your AI assistant include:

• Session management for multiple OpenAPI specifications with persistent format preferences
• Advanced endpoint filtering by tags, HTTP methods, and operational characteristics
• Detailed endpoint inspection with selective data retrieval for optimal performance
• Comprehensive component and schema exploration including security schemes
• Tag-based organization understanding for large, complex APIs
• Dynamic output format switching to optimize for specific use cases
• Support for APIs with sophisticated authentication, workflow, and data sensitivity requirements
• Documentation generation with interactive HTML output featuring sticky navigation and expanded schemas

This enables your AI to provide contextually accurate assistance whether you're exploring a new API, implementing complex business workflows, debugging integration issues, or extending existing functionality. The tool scales from simple APIs with a few endpoints to enterprise systems with hundreds of endpoints and complex data relationships. The multiple output formats allow your AI to balance between detailed information and token efficiency based on the specific task at hand.

Repository

Source code and issues: https://github.com/DeanWard/janus-mcp