# Stoplight MCP

> Stoplight MCP connects your AI client directly to an API design and documentation system. Use it to audit, review, and map entire API lifecycles without ever leaving your chat window. Quickly inspect schemas, track team activity logs, or check project ownership details using simple conversation prompts.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** openapi, api-design, documentation, api-governance, schema-management, technical-writing

## Description

Managing APIs used to mean jumping between complex dashboards: the schema view, the project roadmap, the activity feed—all separate tabs that kill momentum. This MCP pulls all of that context into your agent. You can ask your AI client for an overview of every workspace or pull up a full OpenAPI schema for a specific endpoint just by talking to it. It lets you run architectural reviews and documentation checks conversationally. When you need this level of technical depth, Vinkius makes sure the Stoplight connection is ready for any MCP-compatible client, letting your agent handle complex tasks like checking recent changes or listing all contributors across multiple projects. You get instant visibility into API structures and development status without needing to click through a single dashboard.

## Tools

### get_node_details
Extracts the full, detailed schema and raw text definition for one selected documentation node.

### get_project_details
Gives high-level metadata and status details for a chosen Stoplight project.

### list_workspace_activity
Fetches recent logs detailing who made changes and what was updated within the workspace.

### list_workspace_members
Lists all users associated with the workspace and their current roles or permissions.

### list_project_nodes
Lists all individual components—files, endpoints, or models—inside a specific API documentation project.

### list_projects
Lists all specific API documentation repositories housed within a single workspace.

### list_workspaces
Retrieves a list of all top-level organizational containers accessible in your Stoplight account.

## Prompt Examples

**Prompt:** 
```
List my Stoplight projects and show recent workspace activity.
```

**Response:** 
```
Connected successfully.
**Projects (`list_projects`)**:
- `Payment V2 Refactor`
- `Internal Logistics API`

**Recent Activity (`list_workspace_activity`)**:
- *alex.dev* updated the `POST /transactions` endpoint with new security parameters.
```

**Prompt:** 
```
Retrieve the detailed schema documentation for the processing node in our core billing API project.
```

**Response:** 
```
Accessing workspace files...

**Node Details (`get_node_details`)**:
Extracted the OpenAPI schema for the `processing` endpoint. It expects a payload including `transactionId`, `amount`, and `currency`. Validation is active. How would you like to review these definitions?
```

**Prompt:** 
```
List all active members in the current workspace.
```

**Response:** 
```
Checking organizational permissions...

**Workspace Members (`list_workspace_members`)**:
- Jane Doe (Admin)
- John Smith (Editor)
- Alex Dev (Viewer)

All 3 members are currently active and mapped to active API projects.
```

## Capabilities

### Map the full architecture
List every accessible workspace, project repository, and individual documentation node within your entire organization.

### Audit team governance
See exactly who owns a project or which members are authorized to contribute to specific API workspaces.

### Track development activity
Pull up recent logs of changes, seeing who updated what endpoint and when across the whole system.

### Inspect schema details
Retrieve the full, structured documentation for any given API node, including its expected data types and parameters.

## Use Cases

### Reviewing a cross-functional dependency update
A backend engineer needs to know if two separate services (Billing and Inventory) are using the same version of a user ID field. They ask their agent to list all nodes in both projects, then use `get_node_details` on the relevant endpoints from each project to compare schemas directly.

### Onboarding a new team member
A platform architect needs to assign roles. They ask their agent to call `list_workspace_members`, then review the output to see who has editing permissions, and finally check project details using `get_project_details` to confirm scope.

### Tracking a critical bug fix deployment
A technical writer asks their agent for recent activity. The agent calls `list_workspace_activity`, providing the exact timestamp and user who updated the API, allowing the writer to write accurate release notes.

### Mapping out a new feature scope
An architect wants to see all potential areas for a new payment gateway. They first use `list_workspaces` to define the boundaries, then run `list_projects` inside that workspace to catalog every existing API repository.

## Benefits

- You cut out the dashboard-hopping. Instead of navigating through multiple tabs to see project structure, you simply ask your agent for a list of all projects using `list_projects` and get immediate results.
- Stop manual documentation reviews. Need to know if an endpoint changed? Use `list_workspace_activity` to pull up recent logs instantly, letting you track changes without digging through date-stamped audit tables.
- Deep dive into schemas on demand. Want the full structure of a payment node? Calling `get_node_details` gives you the raw OpenAPI schema immediately, perfect for validation checks.
- Understand team ownership fast. Use `list_workspace_members` to instantly confirm who has admin or editor rights in any given workspace, solving governance questions right away.
- See your whole picture at once. Start with `list_workspaces` to map the entire organizational container structure before drilling down into specific projects like 'core-billing-api'.

## How It Works

The bottom line is that you talk to your AI client, and it handles the complex navigation across Stoplight’s entire library of API definitions.

1. First, authenticate your AI client by installing the Stoplight MCP module into your environment.
2. Next, configure the connection by providing your unique `STOPLIGHT_WORKSPACE` slug and a valid API token.
3. Finally, simply prompt your agent with an action, like 'Show me all projects in core-billing' or 'What were the last 5 changes to this workspace?'

## Frequently Asked Questions

**How does the Stoplight MCP help with API governance?**
The Stoplight MCP provides tools like `list_workspace_members` to track project ownership. You can instantly confirm who has admin rights and which users are contributors across your entire organization's APIs.

**Can I use the Stoplight MCP to check API schema details?**
Yes, calling `get_node_details` retrieves the full OpenAPI schema for any specific node. This is crucial for ensuring type safety across your documentation.

**What if I need to see what changed recently in my APIs using Stoplight MCP?**
You use `list_workspace_activity`. It provides an immediate log of recent changes, telling you which endpoints were updated and by whom, saving you manual checks.

**How many different kinds of API projects can I list with Stoplight MCP?**
You first call `list_workspaces` to see the top-level groupings. Then, running `list_projects` inside that workspace shows all contained documentation repositories.

**Does the Stoplight MCP require specific credentials?**
Yes, you must authenticate and provide your `STOPLIGHT_WORKSPACE` slug along with a valid API token to connect the agent to your account data.