# Insomnia MCP

> Insomnia (Collaborative API Design) brings your entire API design process into conversation. List organizations, projects, and files across Insomnia Cloud. Your agent can pull full OpenAPI specifications, audit mock server statuses, and track team progress without you ever touching the desktop app.

## Overview
- **Category:** loved-by-devs
- **Price:** Free
- **Tags:** api-design, rest-api, graphql, debugging, api-testing, websocket

## Description

You handle complex APIs all day long. Usually, that means jumping between a documentation page, a project dashboard, and a local editor just to check an environment variable or grab a specific request payload. This MCP lets your agent take over that context switching. You can ask it things like, 'Show me the full spec for the Payments API file' or 'What are the active mock servers in the Inventory project?' Your AI client pulls all that data—the org structure, the environment variables, and the OpenAPI specs—and gives you a clean answer right where you are typing. It’s about getting answers on demand, not navigating menus. By connecting to Vinkius, you get access to this entire catalog of specialized connectors, making your whole development stack accessible through natural conversation.

## Tools

### list_orgs
Lists every organization in Insomnia Cloud, providing the necessary ID to proceed with project or file actions.

### list_projects
Retrieves a list of all team projects within an organization, which group related API specs and environments.

### list_files
Locates specific files in a project by name or type, including API definitions and request collections.

### get_file
Pulls the full details of an Insomnia file, returning its complete content payload for analysis.

### list_branches
Tracks collaborative progress by listing all available feature branches attached to a specific API definition.

### list_collaborators
Identifies all registered members in the organization, including their roles and access levels.

### list_ai_requests
Lists usage metrics and metadata for AI-powered API requests, showing generated specs and suggested tests.

### get_user
Retrieves the authenticated Insomnia user's profile details, including their current plan and organization memberships.

### list_environments
Lists all defined environments within a project, showing key variables like base URLs and tokens for different stages.

### list_mocks
Provides an inventory of mock servers in a project, including their operational status (active/inactive) and public URL.

## Prompt Examples

**Prompt:** 
```
List all my Insomnia projects in organization 'org-123'
```

**Response:** 
```
I've found 4 projects in organization 'org-123': 'Payments API', 'User Authentication', 'Inventory Management', and 'External Webhooks'. Which one would you like to see files for?
```

**Prompt:** 
```
Show me the OpenAPI spec for the 'Payments API' file
```

**Response:** 
```
Retrieving file 'Payments API'… I've fetched the content. It contains a full OpenAPI 3.0 specification with 12 endpoints, including '/charge', '/refund', and '/dispute'. Would you like a summary of the available paths?
```

**Prompt:** 
```
What are the active mock servers in our 'Inventory' project?
```

**Response:** 
```
I've identified 2 mock servers in 'Inventory': 1) 'Production Mock' (Status: Active, URL: https://mock.insomnia.rest/inv-prod), 2) 'Beta Features' (Status: Inactive). Would you like to check the environment variables for the production mock?
```

## Capabilities

### Discovering Project Structure
List all organizations and team projects to understand the full scope of API designs across multiple teams.

### Retrieving File Content
Get the exact content, including OpenAPI/Swagger specs or request collections, for any specific design file in your project.

### Auditing Configurations
Review environment variables and list active mock servers to confirm that testing stages are configured correctly.

### Tracking Team Progress
Identify team members, check user roles, or review branches to see who is working on what feature.

### Analyzing AI Usage
Query usage metrics and metadata surrounding previous AI-powered requests and test suggestions within the organization.

## Use Cases

### Reviewing Staging Variables
A QA Engineer needs to confirm that the staging environment uses the correct payment gateway URL. Instead of opening Insomnia, they ask their agent to run `list_environments`. The MCP returns a list showing variable counts and confirms the specific base URL for testing.

### Initial Project Assessment
A new Software Architect joins the team and needs an overview of all API definitions. They ask their agent to use `list_orgs` followed by `list_projects`. This immediately maps out every service in the organization, saving hours of manual discovery.

### Debugging Failed Tests
An API Developer's test fails because they suspect an outdated spec. They use their agent to run `list_files` and find the correct file ID, then call `get_file` to pull the absolute latest OpenAPI specification for immediate review.

### Checking Mock Status Before Deployment
A developer needs to verify which services are ready for integration testing. They ask their agent to run `list_mocks`, getting a real-time list of mock servers, their URLs, and whether they are currently active.

## Benefits

- Stop clicking through menus. Instead of opening the Insomnia GUI to see what variables are in place, simply ask for a list of environments using `list_environments` and get the data directly into your chat window.
- Never lose an API spec again. You can use `list_files` to find any design document by name, and then use `get_file` to pull the full OpenAPI specification content instantly.
- Keep track of who owns what. Use `list_collaborators` to identify team members' roles, or check your own status with `get_user`. This keeps project accountability clear without jumping tabs.
- Audit testing environments efficiently. Instead of manually checking multiple dashboards, run `list_mocks` to see all simulated APIs and their current operational states at a glance.
- Track complex feature work. If you need to know if your code changes are isolated, use `list_branches` to review the status across parallel development lines.

## How It Works

The bottom line is that your agent acts as a conversational window into your entire API design platform, letting you get data without opening the app.

1. Subscribe to this MCP in Vinkius and enter your Insomnia Personal Access Token.
2. Tell your AI client exactly what data you need, like 'List all projects for the Payments team.'
3. The MCP runs the request against Insomnia Cloud and sends the raw project list or file content back to your agent.

## Frequently Asked Questions

**How do I list all my Insomnia projects using the Insomnia (Collaborative API Design) MCP?**
You use the `list_projects` tool. This function retrieves a comprehensive list of every team project within your organization, giving you their names and unique IDs.

**Can I check mock server status with Insomnia (Collaborative API Design) MCP?**
Yes, run the `list_mocks` tool. It provides a list of all mock servers linked to your project, including their current operational status and public URLs.

**How do I find out which team members have access? (Insomnia (Collaborative API Design) MCP)**
Use the `list_collaborators` tool. This function lists all registered users in your organization, showing their roles and specific access levels.

**What if I need to see variable counts for different environments? (Insomnia (Collaborative API Design) MCP)**
Run `list_environments`. This tool lists all project environments and shows the associated variable count, helping you confirm which configurations are available.

**Does this MCP support GraphQL or only REST APIs?**
No. The Insomnia (Collaborative API Design) MCP supports a wide range of protocols including REST, GraphQL, gRPC, and WebSockets, as listed in the tool descriptions.