Apidog Sync - MCP Server

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