PA-Endpoints MCP Server

Model Context Protocol (MCP) server for discovering and querying aggregated API endpoints from multiple Swagger/OpenAPI sources.

Overview

PA-Endpoints MCP Server provides AI agents with tools to:

• List Services - Browse all configured API services with metadata
• Search Endpoints - Find endpoints using flexible queries across all services
• Get Details - Retrieve comprehensive endpoint information including parameters and schemas

Perfect for AI-assisted API discovery, documentation exploration, and integration planning.

Installation

Using npx (Recommended)

No installation needed - run directly:

npx @feathered_wolf/pae-mcp --api-url http://localhost:8080

Global Installation

npm install -g @feathered_wolf/pae-mcp

Quick Start

1. Start the PA-Endpoints .NET API (required):

   cd src/api/PA.Endpoints.Api
   dotnet run

2. Run the MCP server:

   npx @feathered_wolf/pae-mcp --api-url http://localhost:8080

The server communicates via stdin/stdout following the MCP protocol and can be used with any MCP-compatible client.

Usage

Command Line

pae-mcp [options]

Options:

• --api-url <url> - API base URL (default: http://localhost:8080)
• --log-level <level> - Log level: error, warn, info, debug (default: info)
• --version - Show version number
• --help - Display help information

Environment Variables

Create a .env file:

API_URL=http://localhost:8080
MCP_SERVER_NAME=pae-mcp
LOG_LEVEL=info

Configuration

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pa-endpoints": {
      "command": "npx",
      "args": [
        "@feathered_wolf/pae-mcp",
        "--api-url",
        "http://localhost:8080",
        "--log-level",
        "info"
      ]
    }
  }
}

MCP Tools

list_services

Lists all configured API services or endpoints for a specific service.

Parameters:

• service_id (optional) - Get endpoints for a specific service
• tags (optional, array) - Filter services by tags
• enabled_only (optional, boolean, default: true) - Only return enabled services

Examples:

List all services:

{
  "name": "list_services",
  "arguments": {}
}

Get endpoints for a service:

{
  "name": "list_services",
  "arguments": {
    "service_id": "petstore"
  }
}

search_endpoints

Search for API endpoints across all services using flexible query syntax.

Parameters:

• query (required, string) - Search keywords, path, or method
• service_names (optional, array) - Filter by service names
• methods (optional, array) - Filter by HTTP methods (GET, POST, PUT, DELETE, PATCH)
• limit (optional, number, default: 50, max: 500) - Maximum results

Examples:

Search by keyword:

{
  "name": "search_endpoints",
  "arguments": {
    "query": "user"
  }
}

Search with filters:

{
  "name": "search_endpoints",
  "arguments": {
    "query": "order",
    "methods": ["POST", "PUT"],
    "service_names": ["ecommerce-api"],
    "limit": 10
  }
}

get_endpoint_details

Get comprehensive information about a specific endpoint.

Parameters:

• endpoint_id (required, string) - Unique endpoint identifier (format: service-method-path)
• include_examples (optional, boolean, default: true) - Include JSON schema examples

Example:

{
  "name": "get_endpoint_details",
  "arguments": {
    "endpoint_id": "petstore-get-/pet/{petId}",
    "include_examples": true
  }
}

Troubleshooting

Connection Errors

Error: ECONNREFUSED or ENOTFOUND

Solution:

1. Verify .NET API is running: curl http://localhost:8080/api/services
2. Check API_URL configuration
3. Ensure firewall allows connections

No Results

Issue: Search returns no endpoints

Solution:

1. Verify services are configured in API
2. Check API logs for Swagger fetch errors
3. Ensure services are enabled

Configuration Error

Error: Configuration not initialized

Solution:

• Provide API_URL via --api-url flag or .env file

Development

Prerequisites

• Node.js >=18.0.0
• npm >=9.0.0
• PA-Endpoints .NET API

Setup

git clone <repository-url>
cd src/mcp-server
npm install

Build

npm run build

Test

# Run all tests
npm test

# Watch mode
npm run test:watch

# Specific test
npm test -- search-endpoints.test.ts

Lint

npm run lint

Development Mode

npm run dev

Local Testing

# Build and link locally
npm run build
npm link

# Test globally
pae-mcp --help
pae-mcp --api-url http://localhost:8080

# Unlink
npm unlink -g @feathered_wolf/pae-mcp

Architecture

┌─────────────────┐
│   AI Assistant  │
│  (Claude, etc)  │
└────────┬────────┘
         │ MCP Protocol
         │ (stdin/stdout)
┌────────▼────────┐
│   MCP Server    │
│  (this package) │
├─────────────────┤
│ • list_services │
│ • search        │
│ • get_details   │
└────────┬────────┘
         │ HTTP REST
┌────────▼────────┐
│  PA-Endpoints   │
│    .NET API     │
└─────────────────┘

Components:

• Server - MCP protocol handler and tool registry
• API Client - HTTP client with retry logic
• Tools - Three endpoint discovery tools
• Logger - Winston-based structured logging
• Errors - Custom error classes with MCP formatting

Requirements

• Runtime: Node.js >=18.0.0
• Backend: PA-Endpoints .NET API (must be running)

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass: npm test
5. Follow existing code style: npm run lint
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Issues: File issues on GitHub
• Documentation: See /docs directory
• API Documentation: http://localhost:8080/swagger (when API running)

Built with Model Context Protocol