# OpenAPI Spec Validator MCP for AI Agents MCP

> OpenAPI Spec Validator MCP for finding broken API definitions, unused components, and parameter mismatches in your OAS 3.x files before they break your production environment.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_V1QKieQHr04kwSsAMtuL8ZVmEHdjZWhSZII2jPnG/mcp
- **Tags:** openapi, swagger, api-spec, validation, automation

## Description

Writing an API spec is hard enough without realizing three days later that you forgot to define a required field or left a bunch of dead schemas floating around. This MCP acts as a dedicated auditor for your OpenAPI documents. It scans your files to catch structural errors, identifies components that aren't actually being used, and makes sure your path parameters actually match their definitions. Instead of manually hunting through hundreds of lines of YAML, you just point your agent at the file and let it find the inconsistencies. Since this is part of the Vinkius catalog, you can connect it to Claude or Cursor and start auditing immediately without any complex setup.

## Prompt Examples

**Prompt:** 
```
Are there any unused parts in this spec?
```

**Response:** 
```
| I found several orphaned components in your document: <br><br> • **Schemas**: `User`, `Address`, `Metadata`<br> • **Parameters**: `X-Request-ID`<br><br> You can safely remove these to clean up your file.
```

**Prompt:** 
```
Check if my path parameters are all set up correctly.
```

**Response:** 
```
| I found a mismatch in the `/orders/{orderId}` path. The `{order_id}` variable is present in the URL template, but there is no corresponding definition in the parameters section.
```

**Prompt:** 
```
Does this schema have everything it needs?
```

**Response:** 
```
| There is an integrity issue in `ProductSchema`. The property `sku` is listed as a **required** field, but it isn't actually defined in the properties object.
```

## Capabilities

### Catch structural errors in OAS files
Identify high-level syntax mistakes that violate OpenAPI 3.x rules.

### Find unused schemas and parameters
Locate dead code and orphaned components to keep your documentation clean.

### Match path templates with parameter definitions
Ensure every variable in your URL has a corresponding definition.

### Identify missing response definitions
Detect endpoints that lack necessary error or success response documentation.

### Detect undocumented required fields
Find discrepancies where properties are marked as required but not properly defined.

## Use Cases

### Cleaning up legacy specs
You have a massive, messy Swagger file. You ask your agent to run detect_orphaned_components to see what can be safely deleted.

### Verifying new endpoints
You just added /users/{id} but forgot the parameter definition. Your agent uses verify_path_parameter_consistency to flag the error before you commit.

### Preparing for a breaking change
You're updating schemas and need to ensure no required fields were missed. The agent runs audit_response_and_requirement_integrity to verify everything is documented.

### Enforcing structural standards
Your team has strict OAS 3.x rules. You use validate_meta_schema to ensure every new spec meets the company's fundamental structural requirements.

## Benefits

- Stop shipping invalid OAS 3.x files by catching structural errors early with validate_meta_schema.
- Keep your documentation lean by using detect_orphaned_components to prune dead schemas.
- Prevent broken endpoints by running verify_path_parameter_consistency on every path update.
- Ensure contract reliability with audit_response_and_requirement_integrity checking for missing responses.
- Reduce manual review time during pull requests by automating the spec audit process.

## How It Works

The bottom line is you stop shipping broken API documentation.

1. Connect the MCP to your preferred client like Claude or Cursor via Vinkius.
2. Point your agent toward your OpenAPI 3.x specification file.
3. Review the detailed audit report for structural errors and orphaned components.

## Frequently Asked Questions

**How can I find unused schemas in my OpenAPI file with OpenAPI Spec Validator?**
You can ask your agent to scan the document for components that aren't referenced in any paths. It will list every orphaned schema it finds so you can delete them safely.

**Can OpenAPI Spec Validator catch errors in path parameters?**
Yes, it specifically checks if the variables you put in your URL templates actually have matching parameter definitions to prevent broken endpoints.

**Will this MCP help with my API documentation accuracy?**
Absolutely. It audits your specification for missing response definitions and ensures that all required fields are properly documented within your schemas.

**Does OpenAPI Spec Validator support Swagger 2.0?**
This tool is specifically designed for OpenAPI 3.x documents to ensure you are getting the most accurate structural validation available.

**How do I use OpenAPI Spec Validator with Claude or Cursor?**
Since it's hosted on Vinkius, you just connect your client once and you can immediately start asking your agent to audit your API files for errors.

**What does this server check?**
It performs structural checks using `validate_meta_schema`, finds unused components with `detect_orphaned_components`, and verifies path parameters. Tools available: `your_tool_name`.

**Does it support Swagger 2.0?**
No, this tool is specifically designed for OpenAPI 3.x specifications.

**How can I find unused schemas?**
Run the `detect_orphaned_components` tool on the specification content.