# Apiary MCP for AI Agents MCP

> Apiary lets your AI agent manage the entire API life cycle—from initial design blueprint to published documentation and rigorous testing. You can read raw API specifications, update documentation instantly with new markdown code, or run Dredd-style tests against live backends, all without leaving your editor.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** api-design, swagger, documentation, api-blueprints, rest-api, workflow-automation

## Description

Managing APIs used to mean constantly jumping between tools: the design spec file, the documentation portal, and the actual test runner. Now, you can keep your whole process inside a single conversation with your AI agent. This MCP connects directly to your Apiary workspace, letting you take full command of API design and validation through natural language commands.

Whether you're an engineer needing to fetch the current blueprint or a writer updating documentation, your agent handles it. You can instruct it to publish changes, review team projects, and validate endpoints against existing specifications. It’s like having the entire API governance console open right in your chat window. This integration is hosted on Vinkius, giving you access to thousands of other development tools alongside Apiary.

## Tools

### list_apis
Lists every API project available within your connected Apiary workspace.

### get_api
Retrieves the complete, raw source code blueprint for any specific API project.

### publish_blueprint
Updates an existing API project's blueprint using new Markdown or Swagger specification content.

### get_me
Fetches and displays your own authenticated user profile information from Apiary.

### list_team_apis
Shows all API projects that belong to a specific team within the workspace.

### list_teams
Lists every team you are currently a member of in Apiary.

### get_team
Provides detailed information about a specific API team, including its purpose and owners.

### list_team_members
Lists every user belonging to an Apiary team, showing their roles within that group.

### run_tests
Runs Dredd-style API tests against a project blueprint and reports the validation status.

### get_doc_url
Provides the live URLs for both the documentation page and the mock server associated with an API project.

## Prompt Examples

**Prompt:** 
```
Hey, can you give me the current blueprint code for the payments API? I want to see if it still supports refund endpoints.
```

**Response:** 
```
**API Blueprint: Payments Gateway**

*   **Endpoints:** /payments (POST), /refunds (GET)
*   **Status:** Active. Last Updated: 2024-10-05.
*   **Details:** The refund endpoint requires a `transaction_id` and accepts an optional `reason` string. 

```markdown
# Payments API
... (Full Swagger/Markdown code here) ...
```
```

**Prompt:** 
```
I wrote some new documentation for the user service endpoints. Can you publish this markdown update to the 'users-api' project?
```

**Response:** 
```
**✅ Success:** The updated Markdown has been successfully published to `users-api`.

*   **Validation:** Syntax verified as valid Blueprint.
*   **Impact:** Mock server and public documentation URL refreshed automatically.

The new changes are now live for testing.
```

**Prompt:** 
```
Can you check the status of the user management API? I think there might be a bug in the authentication flow.
```

**Response:** 
```
**Dredd Test Report: User Management API**

| Test Case | Status | Details |
| :--- | :--- | :--- |
| `list_users` (GET) | ✅ PASS | Returns 200 OK. Correct schema verified. |
| `create_user` (POST) | ❌ FAIL | Expected HTTP 401, but received 200 OK. Missing required 'role' field.|
```

## Capabilities

### List all available APIs
Retrieves a comprehensive list of every API project configured within your connected Apiary workspace.

### Fetch raw API blueprints
Grabs the full source code for any specific API blueprint, whether it's in Markdown or Swagger format.

### Update and publish documentation
Publishes changes to an existing API project by accepting new markdown content, automatically updating both mock servers and public docs.

### Validate APIs with integrated testing
Executes Dredd-style tests against a specified API blueprint to ensure your backend implementation matches the design specifications.

### Review team structure and members
Manages team permissions by listing all teams you belong to, viewing team details, and seeing every member associated with that group.

## Use Cases

### A new endpoint needs defining
The backend engineer asks their agent to fetch the current blueprint using `get_api`, writes a few lines of Markdown for the new endpoint, and then tells the agent to `publish_blueprint`. The change goes live immediately.

### Checking team compliance
The engineering manager asks their agent to use `list_team_apis` for a specific department. This instantly shows all relevant projects, allowing them to check ownership and ensure proper coverage across the board.

### Validating production changes
Before deploying code, the developer instructs their agent to `run_tests`. The MCP executes Dredd-style tests against the blueprint, providing a detailed pass/fail report instantly within the chat.

### Updating external documentation
The technical writer needs to fix formatting on an old API. They use `get_api` to pull the code, correct it in their editor, and then ask the agent to `publish_blueprint`, pushing the corrected version live.

## Benefits

- Keep documentation synchronized with reality. You can use `publish_blueprint` to update your live project specs directly from a chat prompt, eliminating manual copy-pasting.
- Accelerate validation cycles by letting your agent execute `run_tests`, validating backends against the defined blueprint without switching tools.
- Gain full visibility into team ownership. Use the team management tools like `list_team_members` to quickly see who owns which APIs and manage permissions.
- Never lose track of specs again. With `get_api`, you can instantly fetch raw Markdown or Swagger code for any project, making it easy to share with teammates.
- Instantly know where your API lives. The `get_doc_url` tool provides the live documentation and mock server URLs in one shot.

## How It Works

The bottom line is you get full control over your API design and documentation workflow without ever needing to copy anything out of your chat window.

1. Subscribe to this MCP on Vinkius and provide your personal Apiary token.
2. Give your AI client a clear instruction, like 'Check the blueprint for X API' or 'Publish these docs'.
3. The agent interacts with the required tools, fetching raw blueprints, running tests, or pushing updates back to your workspace.

## Frequently Asked Questions

**How does the Apiary MCP help me with API documentation updates?**
It lets you publish changes directly from your conversation window. You provide new markdown code, and the agent publishes it to the live project, automatically updating both the mock server and the public documentation URL.

**Can I use this MCP to test my API endpoints?**
Yes, you can run Dredd-style tests. Simply ask your agent to run tests against a specific blueprint. It executes validation checks and gives you an immediate pass/fail report on the backend implementation.

**Does the Apiary MCP help me manage my API team?**
Absolutely. You can list all APIs owned by your entire department or check who exactly is a member of a specific development team, helping you keep track of ownership and permissions.

**What if I need the raw code for an existing API blueprint?**
You can retrieve the full source code for any API project using the `get_api` tool. This gives you a clean, raw Markdown or Swagger file to work with in your own editor.

**Is this MCP only for single APIs?**
No, it can manage entire portfolios. You can list all available APIs across your whole workspace and even see which projects belong to a specific team.