Apidog Sync MCP Server v2

MCP server for reading, writing, and organizing API documentation in Apidog. Works across Claude Desktop, Claude CLI, Cursor, and Antigravity.

Built on a validated POC: Export → Find → Diff → Merge → Import → Verify.

Tools

Read

| Tool | Description | |------|-------------| | apidog_export_spec | Export full OpenAPI spec | | apidog_list_endpoints | List endpoints (filterable by tag/path/folder/status) | | apidog_get_endpoint | Get full details of a specific endpoint | | apidog_search_endpoints | Fuzzy search by keyword across path/summary/tags/folder |

Write

| Tool | Description | |------|-------------| | apidog_upsert_endpoint | Create or update a single endpoint (with diff + verify) | | apidog_upsert_endpoints | Batch create/update multiple endpoints | | apidog_delete_endpoint | Remove an endpoint | | apidog_upsert_schema | Create or update a component schema | | apidog_import_spec | Import a full or partial OpenAPI spec |

Organize

| Tool | Description | |------|-------------| | apidog_analyze_folders | Analyze current folder structure and stats | | apidog_propose_reorganization | Propose better folder organization (dry-run, no changes) | | apidog_apply_reorganization | Apply a user-validated reorganization plan |

Quick Start

1. Get your Apidog credentials

• Access Token: Apidog → Account Settings → API Access Token → New
• Project ID: Found in your project URL or project settings

2. Add to your MCP client

No installation needed — just add this config block:

{
  "mcpServers": {
    "apidog": {
      "command": "npx",
      "args": ["-y", "apidog-sync-mcp-server"],
      "env": {
        "APIDOG_ACCESS_TOKEN": "your-token",
        "APIDOG_PROJECT_ID": "your-project-id"
      }
    }
  }
}

That's it. npx downloads and runs the server automatically.

Where to put this config

| Client | Config file | |--------|-------------| | Claude Code (global) | ~/.claude.json | | Claude Code (per-project) | .mcp.json in project root | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | | Cursor | .cursor/mcp.json | | Windsurf | MCP settings panel |

Multiple Apidog projects

Use separate entries — each pointing to a different project ID:

{
  "mcpServers": {
    "apidog-frontend": {
      "command": "npx",
      "args": ["-y", "apidog-sync-mcp-server"],
      "env": {
        "APIDOG_ACCESS_TOKEN": "your-token",
        "APIDOG_PROJECT_ID": "frontend-project-id"
      }
    },
    "apidog-backend": {
      "command": "npx",
      "args": ["-y", "apidog-sync-mcp-server"],
      "env": {
        "APIDOG_ACCESS_TOKEN": "your-token",
        "APIDOG_PROJECT_ID": "backend-project-id"
      }
    }
  }
}

Usage Examples

Updating an endpoint after a route change

"I updated the validation rules on the peppol endpoint, the description should say the format must be scheme:identifier with a single colon. Update the docs."

The agent will:

1. Search for the peppol endpoint (apidog_search_endpoints)
2. Get the current format (apidog_get_endpoint)
3. Build the updated operation matching the exact existing format
4. Push the update with diff showing what changed (apidog_upsert_endpoint)
5. Verify the update landed

Reorganizing folders

"Analyze my API folder structure and suggest a better organization"

The agent will:

1. Analyze current folders (apidog_analyze_folders)
2. Propose reorganization (apidog_propose_reorganization)
3. Present the plan and wait for your approval
4. Apply only after you confirm (apidog_apply_reorganization)

Batch updates from route changes

"I added 3 new routes for invoice management: POST /api/v1/invoices, GET /api/v1/invoices/{id}, DELETE /api/v1/invoices/{id}. Add them to the docs."

The agent will:

1. Check existing endpoints to learn the format
2. Build all 3 operations matching the project format
3. Batch upsert them (apidog_upsert_endpoints)

Reorganization Strategies

| Strategy | Description | |----------|-------------| | path-based | Infer folders from URL paths: /api/v1/admin/billing/... → Admin/Billing | | preserve-top-level | Keep existing top-level folders, reorganize sub-levels | | flat | Single level by main resource name |

Custom mappings let you override specific prefixes:

{
  "customMappings": {
    "/api/v1/admin": "Administration",
    "/auth": "Authentication",
    "/api/v1/public": "Public API"
  }
}

Apidog Extensions

Fully supports:

• x-apidog-folder — Folder path: "Safetytracker V1/Super Admin/Billing"
• x-apidog-status — Lifecycle: designing, developing, released, deprecated
• x-apidog-maintainer — Team member assignment
• x-apidog-orders — Field ordering in schema objects
• x-apidog-ignore-properties — Hidden properties
• x-apidog-name — Response display names
• x-apidog-ordering — Response ordering

How Writes Work

Every write operation follows the POC-validated flow:

Export current spec (preserves all formatting)
    ↓
Find target endpoint (exact match or fuzzy search)
    ↓
Compute diff (show what changed)
    ↓
Merge into full spec (deep merge, preserve untouched endpoints)
    ↓
Import with OVERWRITE_EXISTING
    ↓
Verify (re-export and confirm)

No endpoints are lost. No formatting is changed on untouched endpoints.

Development

To run from source (for contributing or local testing):

git clone https://github.com/YOUR_USERNAME/apidog-sync-mcp-server.git
cd apidog-sync-mcp-server
npm install

Then point your MCP config to the local source:

{
  "mcpServers": {
    "apidog": {
      "command": "node",
      "args": ["/path/to/apidog-sync-mcp-server/src/index.js"],
      "env": {
        "APIDOG_ACCESS_TOKEN": "your-token",
        "APIDOG_PROJECT_ID": "your-project-id"
      }
    }
  }
}

License

MIT