AGDevX OpenAPI MCP Server

Turn any OpenAPI specification into MCP tools for AI assistants. Point it at your API's OpenAPI/Swagger spec, and your assistant can instantly interact with your API.

Features

• Dynamic Tool Generation - Automatically creates MCP tools from OpenAPI 3.0/3.1 specifications
• Friendly Tool Names - Smart naming: post_api_v1_users → create_user with helpful descriptions
• Multi-Environment Support - Switch between dev, qa, and other environments per-request
• Live Spec Refresh - Update tools without restarting
• Rate Limiting - Built-in protection with configurable request limits
• Two Transport Methods - stdio (easiest) or HTTP (Docker)
• Easy Setup Wizard - Web-based wizard for non-technical users

Quick Start: Setup Wizard

The easiest way to configure this server is through the web-based setup wizard:

npx agdevx-openapi-mcp-server@latest setup

This launches a browser-based wizard that:

1. Guides you through entering your API details
2. Tests your OpenAPI spec URLs to verify they work
3. Auto-detects which MCP clients you have installed
4. Automatically updates your config file (with backup) or shows you what to copy

Features:

• Visual multi-step wizard
• Real-time URL validation
• Support for multiple environments (dev, qa, etc.)
• Auto-detects VS Code, Claude Desktop, and Claude Code
• Safe auto-update with backups or manual copy option

Options:

# Custom port
npx agdevx-openapi-mcp-server@latest setup --port 3001

# Don't auto-open browser
npx agdevx-openapi-mcp-server@latest setup --no-open

After configuring, restart your MCP client and the server will be available.

Manual Configuration

Configure via environment variables. When using npx, set these in your MCP client config. When using Docker, set them in .env file.

Required Settings

# Define your environments (comma-separated)
ENVIRONMENTS=dev

# OpenAPI spec URL for each environment (used ONLY to fetch the spec)
API_SPEC_URL_PDEV=https://dev-api.example.com/openapi/v1.json

# Base API URL for each environment (used for all API calls)
API_BASE_URL_DEV=https://dev-api.example.com

Multiple Environments

ENVIRONMENTS=dev,qa
DEFAULT_ENVIRONMENT=dev

# OpenAPI spec URLs (used to fetch the spec)
API_SPEC_URL_DEV=https://dev-api.example.com/openapi/v1.json
API_SPEC_URL_QA=https://qa-api.example.com/openapi/v1.json

# Base API URLs (used for API calls)
API_BASE_URL_DEV=https://dev-api.example.com
API_BASE_URL_QA=https://qa-api.example.com

Optional Settings

| Variable | Default | Description | | ------------------------------ | --------------------------- | ------------------------------------------------------------------------------- | | MCP_SERVER_NAME | agdevx-openapi-mcp-server | Give a custom name to the server (e.g., account-api) | | MCP_VERBOSE | false | Enable verbose logging | | PORT | 3000 | Port for HTTP transport (Docker) | | API_TIMEOUT | 30000 | API request timeout (ms) | | NODE_TLS_REJECT_UNAUTHORIZED | 1 (enabled) | TLS certificate verification. Set to 0 to disable for self-signed certs (dev) | | RATE_LIMIT_ENABLED | true | Enable rate limiting | | RATE_LIMIT_REQUESTS | 10 | Max requests per window | | RATE_LIMIT_WINDOW_MS | 60000 | Rate limit window (ms) |

See .env.example for all available options.

Docker Setup (Optional)

Using Pre-Built Images

# Docker Hub
docker pull agdevx/agdevx-openapi-mcp-server:latest

# Run with docker-compose
docker-compose up -d

Building Locally

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Verifying Docker Deployment

# Test the endpoint
curl http://localhost:3001/mcp

# Check logs for successful startup
docker-compose logs -f | grep "initialized successfully"

Client Setup

VS Code

Edit your VS Code MCP config file (mcp.json):

• Windows: %APPDATA%\Code\User\mcp.json
• macOS/Linux: ~/.config/Code/User/mcp.json

{
	"servers": {
		"my-api": {
			"type": "stdio",
			"command": "npx",
			"args": ["agdevx-openapi-mcp-server"],
			"env": {
				"ENVIRONMENTS": "dev",
				"API_SPEC_URL_DEV": "https://dev-api.example.com/openapi/v1.json",
				"API_BASE_URL_DEV": "https://dev-api.example.com"
			}
		}
	}
}

Reload VS Code: Ctrl+Shift+P → "Developer: Reload Window"

Claude Desktop

Edit your Claude Desktop config:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
	"mcpServers": {
		"my-api": {
			"command": "npx",
			"args": ["agdevx-openapi-mcp-server"],
			"env": {
				"ENVIRONMENTS": "dev",
				"API_SPEC_URL_DEV": "https://dev-api.example.com/openapi/v1.json",
				"API_BASE_URL_DEV": "https://dev-api.example.com"
			}
		}
	}
}

Restart Claude Desktop.

Claude Code

# Add the server
claude mcp add my-api --scope user -- npx agdevx-openapi-mcp-server

# Edit config to add environment variables
claude config edit

Add to config file:

{
	"mcpServers": {
		"my-api": {
			"command": "npx",
			"args": ["agdevx-openapi-mcp-server"],
			"env": {
				"ENVIRONMENTS": "dev",
				"API_SPEC_URL_DEV": "https://dev-api.example.com/openapi/v1.json",
				"API_BASE_URL_DEV": "https://dev-api.example.com"
			}
		}
	}
}

Docker (HTTP Transport)

Note: HTTP transport is only supported by VS Code and Claude Desktop. Claude Code does not support HTTP transport.

For VS Code or Claude Desktop, if using Docker instead of npx:

VS Code (mcp.json):

{
	"servers": {
		"my-api": {
			"type": "http",
			"url": "http://localhost:3001/mcp"
		}
	}
}

Claude Desktop (claude_desktop_config.json):

{
	"mcpServers": {
		"my-api": {
			"url": "http://localhost:3001/mcp",
			"transport": "http"
		}
	}
}

Claude Code: Docker/HTTP transport is not supported. Use npx with stdio transport instead (see Claude Code section above).

Testing

Ask Claude:

• "What tools are available from my API?"
• "Get all users from my API"
• "List all available environments"
• "Check server status"

Features

Friendly Tool Names & Descriptions

Tools are automatically named in an intuitive, friendly way:

• post_api_v1_users → create_user
• get_api_v1_users → list_users
• get_api_v1_users_id → get_user
• put_api_v1_users_id → update_user
• delete_api_v1_users_id → delete_user

Enhanced descriptions include required parameters:

• "Create a new user. Requires: name, email, body."
• "Get a single user. Requires: id."
• "List users"

The server intelligently:

• Converts camelCase operationIds to snake_case (getUserProfile → get_user_profile)
• Generates friendly names from HTTP method + resource path
• Handles non-RESTful APIs: Parses camelCase (/searchItems), kebab-case (/calculate-tax), and RPC-style paths
• Recognizes POST operations: POST /users/search → search_user (not create)
• Detects 70+ action words: search, query, filter, calculate, validate, activate, export, enroll, transfer, merge, certify, upsert, publish, fulfill, persist, receive, etc.
• Singularizes resource names (users → user, categories → category)
• Shows required parameters in descriptions

See FRIENDLY_NAMES.md for detailed examples and how it works.

Multiple Environments

Every API tool includes an optional environment parameter. Switch between environments per-request:

# List environments
"List all available environments"

# Use specific environment
"Get account information from the dev environment"

# Compare across environments
"Get user 123 from dev, then from qa"

# See differences between environments
"What's the difference between the APIs running in dev and qa?"

# Change default environment
"Set the default environment to qa"

Management tools:

• list_environments - View all configured environments
• get_current_environment - Check current default
• set_default_environment - Change default
• check_server_status - Health check with environment reachability, rate limits, and tool counts

Refresh Spec Without Restarting

Update your API spec on-the-fly when your API changes:

"Refresh the OpenAPI spec"

This:

• Fetches the latest spec
• Updates existing tools immediately
• Registers new operations
• No restart required

Rate Limiting

Built-in protection with sliding window algorithm:

• Default: 10 requests per 60 seconds
• Configurable via environment variables
• Clear error messages with retry timing

RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS=10
RATE_LIMIT_WINDOW_MS=60000

Server Status & Health Check

Monitor server health and status with the check_server_status tool:

"Check server status"

This provides:

• Environment Status: Shows which environments are reachable with ✓/✗ indicators
• Rate Limit Usage: Current request count vs. limit with time until reset
• Available Tools: Total count of API operations and management tools
• Last Spec Refresh: Time since the OpenAPI spec was last fetched

Example output:

Environments: 2 (dev✓, qa✗ unreachable)
Rate Limit: 3/10 requests used (resets in 45s)
Tools Available: 15
Last Spec Refresh: 2 minutes ago

Use this to:

• Verify all environments are accessible
• Monitor rate limit usage before making bulk API calls
• Confirm spec refreshes are working
• Check total available tools after updates

Troubleshooting

Server Won't Start

"Cannot start MCP server without valid OpenAPI specification"

• Verify API_SPEC_URL is correct in .env or client config
• Test URL manually: curl https://api.example.com/openapi/v1.json
• Ensure API is running and accessible
• For self-signed certificates (dev/testing), set NODE_TLS_REJECT_UNAUTHORIZED=0 in your environment variables

Docker Issues

Port already in use:

# Change in docker-compose.yml
ports:
 - '3002:3000' # Use different port

Container won't start:

# Check logs
docker-compose logs -f

Can't connect from client:

# Verify container is running
docker ps | grep agdevx-openapi-mcp-server

# Test endpoint
curl http://localhost:3001/mcp

No Tools Appearing

• Verify OpenAPI spec is valid (OpenAPI 3.0+)
• Ensure endpoints have operationId in spec
• Check logs: docker-compose logs -f | grep "initialized successfully"
• Restart client application

General Issues

Restart the server:

docker-compose restart
# or
docker-compose down && docker-compose up -d

Enable verbose logging:

MCP_VERBOSE=true

Development

Running Tests

The project includes comprehensive unit tests using Jest:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

See TESTING.md for detailed testing documentation.

Building

# Build TypeScript to JavaScript
npm run build

# Watch mode for development
npm run watch

Feature enhancements

• Whitelists and blacklists: Only allow specific endpoints to be called, or explicitly prevent specific endpoints to be called.