How do I use OpenAPI Directory MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OpenAPI Directory MCP Server search for payment APIs in the directory" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

OpenAPI Directory MCP Server

by rawveg

Overview Schema Related Servers Score Discussions

TypeScript

Remote

A Model Context Protocol (MCP) server that provides access to the APIs.guru directory - the world's largest repository of OpenAPI specifications with over 3,000 API Specs from 600+ providers. Now with custom OpenAPI spec import - seamlessly integrate your own APIs alongside the public directory.

Related MCP server: OpenAPI MCP Server

Acknowledgments

This project builds upon the exceptional work of APIs.guru and their comprehensive OpenAPI Directory. The APIs.guru project maintains the largest repository of machine-readable API definitions, providing an invaluable resource to the developer community through their free API service at https://api.apis.guru/v2.

Their dedication to creating and maintaining this comprehensive directory of OpenAPI specifications makes projects like this possible. We are deeply grateful for their contribution to the open source ecosystem and their commitment to making API discovery accessible to everyone.

The source data is provided under the Creative Commons Zero v1.0 Universal License, reflecting their generous approach to knowledge sharing.

Features

Feature	Description
Zero Configuration	Works out of the box with sensible defaults
Comprehensive API Coverage	Access to 3,000+ API specs from APIs.guru
Custom OpenAPI Import	Import and manage your own APIs with zero-touch integration
Context-Aware Security	Smart security scanning with legitimate pattern recognition
Context Optimized	Progressive discovery reduces context usage by ~95%
Smart Search Results	Relevance ranking + newest versions first + provider priority
Intelligent Caching	24-hour TTL persistent caching with management tools
Rich Tool Set	22 specialized tools for API discovery and endpoint analysis
Slash Commands	All prompts auto-exposed as Claude Code slash commands
Paginated Resources	Efficient data access with pagination support
NPX Ready	Install and run with a single command
Type Safe	Built with TypeScript for reliability

🎯 Context Optimization & Progressive Discovery

This MCP server implements a progressive discovery approach that dramatically reduces context usage, allowing you to explore many more APIs before hitting context limits.

The Problem

Traditional API discovery tools return massive amounts of data that quickly saturate LLM context windows. For example, searching for "social media APIs" and fetching their full specifications could exhaust your context before providing useful answers.

Our Solution: 95% Context Reduction

We've redesigned the discovery workflow into three efficient phases:

🔍 Phase 1: Initial Discovery

search_apis returns minimal, paginated results (20 per page)
openapi://apis/summary provides directory overview
Quick browsing of 1,000+ APIs without context overload

📋 Phase 2: Basic Evaluation

get_api_summary provides essential details without endpoints
Authentication, documentation, categories, and provider info
Compare multiple APIs efficiently

⚙️ Phase 3: Detailed Analysis

get_endpoints shows paginated endpoint lists (30 per page)
get_endpoint_details for specific endpoint information
get_endpoint_schema and get_endpoint_examples for implementation

Smart Prompts Guide You

All 22 built-in prompts automatically use this progressive approach:

api_discovery guides you through efficient API exploration
api_integration_guide uses progressive endpoint discovery
Each prompt prevents context saturation while maximizing useful information

🚀 Quick Start

Local Development Setup

Clone and build:

git clone https://github.com/rawveg/openapi-directory-mcp.git
cd openapi-directory-mcp
npm install
npm run build

Test locally:

node dist/index.js

Configuration for Local Development

Claude Desktop (Local)

{
  "mcpServers": {
    "openapi-directory": {
      "command": "node",
      "args": ["/path/to/openapi-directory-mcp/dist/index.js"],
      "cwd": "/path/to/openapi-directory-mcp"
    }
  }
}

Claude Code (Local)

claude mcp add openapi-directory -- node /absolute/path/to/openapi-directory-mcp/dist/index.js

Cursor (Local)

{
  "mcpServers": {
    "openapi-directory": {
      "command": "node",
      "args": ["/path/to/openapi-directory-mcp/dist/index.js"],
      "cwd": "/path/to/openapi-directory-mcp"
    }
  }
}

Windsurf (Local)

{
  "servers": {
    "openapi-directory": {
      "command": "node /path/to/openapi-directory-mcp/dist/index.js"
    }
  }
}

NPX Installation

npx -y openapi-directory-mcp

Claude Desktop (NPX)

{
  "mcpServers": {
    "openapi-directory": {
      "command": "npx",
      "args": ["-y", "openapi-directory-mcp"]
    }
  }
}

Claude Code (NPX)

claude mcp add openapi-directory -- npx -y openapi-directory-mcp

Claude Code MCP Management:

# List all configured MCP servers
claude mcp list

# Get details about the server
claude mcp get openapi-directory

# Remove the server
claude mcp remove openapi-directory

# Check server status in chat
/mcp

🎯 Claude Code Slash Commands: All 22 MCP prompts are automatically available as slash commands!

Core Discovery & Analysis:

/openapi-directory:api_discovery - Discover APIs for specific use cases
/openapi-directory:api_integration_guide - Generate integration guides
/openapi-directory:api_comparison - Compare multiple APIs
/openapi-directory:authentication_guide - Understand API authentication
/openapi-directory:code_generation - Generate code examples
/openapi-directory:api_documentation_analysis - Analyze API capabilities
/openapi-directory:troubleshooting_guide - Debug integration issues

Action-Oriented Code Generation:

/openapi-directory:retrofit_api_client - Retrofit existing codebase with typed API client
/openapi-directory:api_type_generator - Generate TypeScript/language types from specs
/openapi-directory:api_test_suite - Create comprehensive test suites
/openapi-directory:api_error_handler - Build robust error handling with retry logic
/openapi-directory:api_migration_assistant - Migrate between API versions/providers
/openapi-directory:api_sdk_wrapper - Generate custom SDK wrappers
/openapi-directory:api_webhook_scaffold - Scaffold webhook handlers
/openapi-directory:api_rate_limiter - Implement intelligent rate limiting
/openapi-directory:api_graphql_wrapper - Create GraphQL wrappers for REST APIs
/openapi-directory:api_batch_processor - Build batch processing systems

Authentication-Focused:

/openapi-directory:api_auth_implementation - Complete auth implementation
/openapi-directory:api_auth_flow_generator - Generate OAuth2/OIDC flows
/openapi-directory:api_auth_middleware - Build auth middleware for frameworks
/openapi-directory:api_auth_test_harness - Create auth testing tools
/openapi-directory:api_auth_debugger - Debug authentication issues

Cursor (NPX)

{
  "mcpServers": {
    "openapi-directory": {
      "command": "npx",
      "args": ["-y", "openapi-directory-mcp"]
    }
  }
}

Windsurf (NPX)

{
  "servers": {
    "openapi-directory": {
      "command": "npx -y openapi-directory-mcp"
    }
  }
}

📁 Custom OpenAPI Specifications

Import and manage your own OpenAPI specifications alongside the public API directory. Custom specs are treated as first-class citizens with complete integration across all tools and prompts.

✨ Key Features

🎯 Frictionless Import: Single command import from files or URLs
🔒 Context-Aware Security Scanning: Intelligent detection of security issues with legitimate pattern recognition
⚡ Zero-Touch Integration: Works seamlessly with all 22 existing tools and prompts
🏆 Custom Always Wins: Custom specs take precedence over any conflicts
📊 Interactive Management: Full CLI for listing, removing, and maintaining specs
🔄 YAML/JSON Support: Automatic conversion and validation
📂 Hierarchical Storage: Organized in custom/name/version structure

🚀 Quick Start

Import a Custom Spec

# Interactive guided import (recommended for first time)
openapi-directory-mcp --import

# Direct import from local file
openapi-directory-mcp --import ./my-api.yaml --name my-api --version v1

# Import from URL with strict security scanning
openapi-directory-mcp --import https://api.example.com/openapi.json --name example-api --version v2 --strict-security

# Import with custom security options
openapi-directory-mcp --import ./internal-api.yaml --name internal-api --version v1 --skip-security

Manage Custom Specs

# List all imported custom specs
openapi-directory-mcp --list-custom

# Remove a custom spec
openapi-directory-mcp --remove-custom my-api:v1

# Re-run security scan on existing spec
openapi-directory-mcp --rescan-security my-api:v1

# Validate integrity of all custom specs
openapi-directory-mcp --validate-integrity

# Repair any integrity issues
openapi-directory-mcp --repair-integrity

🛡️ Security Scanning

Built-in context-aware security scanner that understands the difference between legitimate code patterns and actual security risks:

Security Rules

Rule	Severity	Description
Code Injection	Critical	Detects `eval()`, `exec()`, script injection patterns
Path Traversal	High	Identifies `../`, directory traversal attempts
SQL Injection	High	Finds SQL injection patterns and keywords
XSS Patterns	High	Detects cross-site scripting vulnerabilities
Hardcoded Secrets	Medium	Identifies API keys, tokens, passwords
Unsafe URLs	Medium	Flags suspicious domains and protocols
Command Execution	Critical	Detects system command execution patterns

Context-Aware Intelligence

The scanner understands legitimate patterns in examples:

# ✅ This is SAFE - Scanner recognizes it's in an example
paths:
  /logs/analyze:
    post:
      examples:
        datadog_query:
          value: 
            query: "eval(sum:system.cpu.usage{*})"  # Datadog query syntax

Security Modes

Normal (default): Scans and reports issues, allows import
Strict: Blocks import if any high/critical issues found
Skip: Bypasses security scanning entirely

📂 Storage Architecture

Custom specs are stored in a hierarchical structure matching the API directory format:

~/.cache/openapi-directory-mcp/custom-specs/
├── manifest.json                    # Master index of all custom specs
└── custom/                          # All custom specs use "custom" provider
    ├── my-api/
    │   ├── v1.json                  # Normalized OpenAPI spec
    │   └── v2.json
    ├── internal-api/
    │   └── v1.json
    └── third-party-api/
        └── v1.json

🔄 Triple-Source Architecture

The MCP server now operates as a triple-source system:

graph TD
    A[MCP Client Request] --> B[Triple-Source API Client]
    B --> C[Custom Specs - Highest Priority]
    B --> D[Secondary APIs - Medium Priority]  
    B --> E[APIs.guru - Base Priority]
    
    C --> F{Found in Custom?}
    F -->|Yes| G[Return Custom Result]
    F -->|No| H{Found in Secondary?}
    H -->|Yes| I[Return Secondary Result]
    H -->|No| J[Return Primary Result]

Precedence Rules: Custom > Secondary > Primary (Custom Always Wins)

🔧 CLI Reference

Import Commands

--import [PATH/URL]     # Import spec (interactive if no path provided)
--name NAME             # Specify name for the imported spec  
--version VERSION       # Specify version for the imported spec
--skip-security         # Skip security scanning during import
--strict-security       # Block import on any medium+ security issues

Management Commands

--list-custom           # List all imported custom specs with details
--remove-custom ID      # Remove a custom spec (format: name:version)
--rescan-security ID    # Re-run security scan on existing spec
--validate-integrity    # Check integrity of custom spec storage
--repair-integrity      # Repair integrity issues automatically

General Commands

--help, -h              # Show help message with all commands

💡 Usage Examples

Interactive Import Workflow

$ openapi-directory-mcp --import

📋 Custom OpenAPI Spec Import Wizard
==================================================

📂 Enter the path or URL to your OpenAPI spec: ./company-api.yaml
🔍 Validating specification...
✅ Valid OpenAPI specification detected
📝 Enter a name for this API: company-api
🏷️  Enter a version identifier: v1.2.0
🔒 Security scanning? (strict/normal/skip) [normal]: normal

📦 Ready to import:
   Source: ./company-api.yaml
   Name: company-api
   Version: v1.2.0
   Security: normal

Proceed with import? (Y/n): y

📥 Importing OpenAPI spec from: ./company-api.yaml
📝 Name: company-api, Version: v1.2.0
🔍 Processing and validating specification...
🔒 Security scan completed:
✅ No security issues found
💾 Storing specification...
✅ Successfully imported custom spec: custom:company-api:v1.2.0

Direct Import Examples

# Import internal API with security scanning disabled
openapi-directory-mcp --import ./internal-api.yaml --name internal --version v1 --skip-security

# Import public API with strict security requirements
openapi-directory-mcp --import https://api.github.com/openapi.json --name github --version v3 --strict-security

# Import development API with normal security scanning
openapi-directory-mcp --import ./dev-api.json --name dev-api --version latest

Management Examples

# List all custom specifications
$ openapi-directory-mcp --list-custom

📚 Custom OpenAPI Specifications (3)
============================================================

1. company-api:v1.2.0
   📋 Company Internal API
   📄 Internal API for company services and data access
   📅 Imported: 12/15/2024 | 📊 156KB YAML
   🔒 Security: ✅ 0 issues | 📦 Source: file

2. github:v3
   📋 GitHub REST API
   📄 GitHub's REST API for repository and user management
   📅 Imported: 12/14/2024 | 📊 2.1MB JSON
   🔒 Security: ⚠️ 2 issues | 📦 Source: url

3. dev-api:latest
   📋 Development API
   📄 Development environment API for testing
   📅 Imported: 12/13/2024 | 📊 45KB JSON
   🔒 Security: ✅ 0 issues | 📦 Source: file

💾 Total: 3 specs, 2.3MB

🔌 Seamless Integration

Once imported, custom specs work automatically with all existing functionality through intelligent API routing and parameter recognition:

Tools Integration

// All 22 tools work with custom specs automatically with intelligent routing

// Search automatically prioritizes custom specs
const results = await search_apis({ query: "company" });
// Returns: custom:company-api:v1.2.0 first (if matches), then public APIs

// Get details works with automatic parameter recognition
const details = await get_api_summary({ api_id: "custom:company-api:v1.2.0" });

// Endpoint analysis works identically with smart routing
const endpoints = await get_endpoints({ api_id: "custom:company-api:v1.2.0" });

Prompts Integration

# All 22 prompts work with custom specs automatically

# API discovery finds custom specs first
/openapi-directory:api_discovery
# Arguments: { use_case: "internal data access" }
# Result: Discovers and recommends custom:company-api:v1.2.0

# Integration guides work seamlessly
/openapi-directory:api_integration_guide  
# Arguments: { api_name: "custom:company-api:v1.2.0", language: "Python" }
# Result: Complete integration guide using your custom spec

# Code generation uses custom specs
/openapi-directory:code_generation
# Arguments: { api_id: "custom:company-api:v1.2.0", endpoint: "/users" }
# Result: Generated code for your custom API endpoints

Resources Integration

// Resources automatically include custom specs with priority handling

// Providers list dynamically includes "custom" when specs exist
const providers = await readResource("openapi://providers");
// Returns: [..., "custom"] (only when custom specs are imported)

// Paginated APIs automatically prioritize custom specs
const apis = await readResource("openapi://apis/page/1");
// Custom specs appear first, then public APIs

// Summary automatically aggregates custom specs in metrics
const summary = await readResource("openapi://apis/summary");
// Directory counts and popular lists seamlessly include custom specs

🎯 Best Practices

Naming Conventions

# Use semantic versioning
--name my-api --version v1.0.0
--name my-api --version v1.1.0-beta

# Use descriptive names
--name user-management-api --version v2
--name payment-gateway-api --version production
--name analytics-api --version latest

Security Recommendations

# For production APIs, use strict scanning
--strict-security

# For internal/development APIs, use normal scanning
# (default behavior)

# Only skip security for trusted, internal-only APIs
--skip-security

Version Management

# Import new versions as separate entries
openapi-directory-mcp --import ./api-v1.yaml --name my-api --version v1
openapi-directory-mcp --import ./api-v2.yaml --name my-api --version v2

# Remove old versions when no longer needed
openapi-directory-mcp --remove-custom my-api:v1

Storage Maintenance

# Regular integrity checks
openapi-directory-mcp --validate-integrity

# Automatic repairs when needed
openapi-directory-mcp --repair-integrity

# Clean up unused specs
openapi-directory-mcp --list-custom  # Review list
openapi-directory-mcp --remove-custom old-api:v1

🚨 Error Handling

Common Import Issues

Error	Cause	Solution
Invalid OpenAPI spec	Malformed YAML/JSON	Validate spec with OpenAPI tools
Name already exists	Duplicate name:version	Use different version or remove existing
Security issues found	Potential security risks	Review issues, use `--skip-security` if safe
File not found	Invalid path	Check file path and permissions
Network error	URL unreachable	Verify URL and network connectivity

Integrity Issues

# Check for issues
$ openapi-directory-mcp --validate-integrity
❌ Found 2 integrity issues:
   • Missing spec file: custom:old-api:v1
   • Orphaned file: custom/unknown-api/v1.json

# Repair automatically
$ openapi-directory-mcp --repair-integrity
✅ Repaired 2 issues:
   • Removed orphaned manifest entry: custom:old-api:v1
   • Cleaned up orphaned file: custom/unknown-api/v1.json

🔧 Environment Configuration

Custom specs respect the same environment variables:

# Change cache directory for custom specs
export OPENAPI_DIRECTORY_CACHE_DIR=/custom/cache/path

# Custom specs will be stored at:
# /custom/cache/path/custom-specs/

⚡ Automatic Cache Invalidation

The system uses a flag file approach for seamless cache synchronization between CLI operations and the running MCP server:

How It Works

Import/Remove Operations: When you import or remove custom specs via CLI, a .invalidate flag file is created
Automatic Detection: The MCP server checks for this flag on every cache access
Instant Invalidation: If the flag exists, cache is cleared and the flag is removed
Zero Restart Required: Changes are immediately visible without restarting Claude Desktop or the MCP server

Technical Benefits

Cross-Process Communication: CLI and MCP server communicate via filesystem flags
Immediate Consistency: No stale cache issues when importing new specs
Performance Optimized: Only invalidates when actual changes occur
Bulletproof: Works across all operating systems and process architectures

# This workflow now works seamlessly:
openapi-directory-mcp --import ./new-api.yaml --name new-api --version v1
# ↑ Creates .invalidate flag

# Immediately available in Claude Desktop (no restart needed)
# ↑ MCP server detects flag, clears cache, removes flag

🛠️ Available Tools

All 22 tools seamlessly support custom imported APIs with zero configuration required. Custom APIs are automatically prioritized in search results and tool responses.

Core API Discovery Tools (Context Optimized)

Tool	Description
`get_providers`	List all API providers
`get_provider_apis`	Get APIs for a specific provider
`get_provider_services`	Get services for a provider
`get_api`	Get detailed API information
`list_all_apis`	⚠️ Use with caution - Returns massive data
`get_metrics`	Directory statistics
`search_apis`	🎯 Smart search: custom APIs first + relevance ranking + newest versions (20/page)

Progressive Discovery Tools (Recommended)

Tool	Description
`get_api_summary`	📋 Phase 2 - Basic API info without endpoints
`get_endpoints`	⚙️ Phase 3 - Paginated endpoint list (30 per page)
`get_endpoint_details`	⚙️ Phase 3 - Detailed endpoint information
`get_endpoint_schema`	⚙️ Phase 3 - Request/response schemas
`get_endpoint_examples`	⚙️ Phase 3 - Request/response examples

Utility Tools

Tool	Description
`get_popular_apis`	Get popular APIs
`get_recently_updated`	Get recently updated APIs
`get_provider_stats`	Provider statistics
`get_openapi_spec`	Fetch OpenAPI specifications
`analyze_api_categories`	Analyze API categories

Cache Management Tools

Tool	Description
`cache_stats`	Get cache statistics and usage info
`list_cache_keys`	List all cached keys with total count
`clear_cache`	Clear all cache entries
`clear_cache_key`	Clear a specific cache key
`cache_info`	Get cache configuration and settings

📦 Available Resources

Context-Optimized Resources

Resource	Description
`openapi://providers`	Complete provider list
`openapi://metrics`	Directory metrics
`openapi://apis/summary`	🎯 Recommended - Directory overview with popular APIs

Paginated API Resources

Resource	Description
`openapi://apis/page/1`	🔍 Phase 1 - APIs 1-50 with minimal data
`openapi://apis/page/2`	🔍 Phase 1 - APIs 51-100 with minimal data
`...`	Pages 1-20 available (50 APIs per page)
`openapi://apis/page/20`	🔍 Phase 1 - APIs 951-1000 with minimal data

Note: The previous openapi://list resource has been removed as it exceeded context limits with massive data. Use the paginated openapi://apis/page/N resources or openapi://apis/summary instead.

💡 Available Prompts (Context-Optimized)

All prompts automatically use the progressive discovery workflow to prevent context saturation.

🎯 Claude Code Users: All prompts below are available as slash commands! Just type /openapi-directory: and you'll see all available commands with descriptions.

Core Discovery & Analysis Prompts

Prompt	Purpose	Workflow
`api_discovery`	🎯 Most Popular - Discover APIs for use cases	3-phase progressive discovery
`api_integration_guide`	Step-by-step integration guide for APIs	Progressive endpoint exploration
`api_comparison`	Compare multiple APIs for functionality	Efficient API summaries
`authentication_guide`	Understand API authentication methods	Focused auth analysis
`code_generation`	Generate code examples for API usage	Endpoint-specific examples
`api_documentation_analysis`	Analyze API capabilities and limitations	Progressive capability mapping
`troubleshooting_guide`	Debug API integration issues	Targeted problem analysis

Action-Oriented Code Generation Prompts

Prompt	Purpose	Use Case
`retrofit_api_client`	Retrofit existing codebase with typed API client	Modernize legacy integrations
`api_type_generator`	Generate TypeScript/language types from OpenAPI specs	Type safety & IDE support
`api_test_suite`	Create comprehensive test suites for API integrations	Quality assurance & CI/CD
`api_error_handler`	Build robust error handling with retry logic	Production reliability
`api_migration_assistant`	Migrate between different API versions/providers	API modernization
`api_sdk_wrapper`	Generate custom SDK wrappers around APIs	Developer experience
`api_webhook_scaffold`	Scaffold webhook handlers and verification	Event-driven architectures
`api_rate_limiter`	Implement intelligent rate limiting	API quota management
`api_graphql_wrapper`	Create GraphQL wrappers for REST APIs	Modern API interfaces
`api_batch_processor`	Build batch processing systems for API calls	High-volume operations

Authentication-Focused Prompts

Prompt	Purpose	Auth Types
`api_auth_implementation`	Complete auth implementation for any API	OAuth2, Bearer, API Key, Basic
`api_auth_flow_generator`	Generate OAuth2/OIDC authorization flows	OAuth2, OIDC, PKCE
`api_auth_middleware`	Build auth middleware for frameworks	Express, FastAPI, Spring
`api_auth_test_harness`	Create auth testing and validation tools	Unit & integration tests
`api_auth_debugger`	Debug authentication issues and flows	Token inspection, flow tracing

💡 Pro Tips:

Start with api_discovery for any use case - guides you through efficient exploration
Use retrofit_api_client to modernize existing codebases with proper API clients
Try api_auth_implementation for complete authentication solutions with any API

Configuration

The server works with zero configuration but supports customization via environment variables:

export CACHE_TTL=86400000  # Cache TTL in milliseconds (default: 24 hours)
export DISABLE_CACHE=false  # Disable caching (default: false)
export OPENAPI_DIRECTORY_CACHE_DIR=~/.cache/openapi-directory-mcp  # Cache directory
export PRIMARY_API_BASE_URL=https://api.apis.guru/v2  # Primary API URL
export SECONDARY_API_BASE_URL=https://api.openapidirectory.com  # Secondary API URL

🧑‍💻 Example Usage

🎯 Progressive Discovery Workflow (Recommended)

// Phase 1: Initial Discovery (Context-efficient search with relevance ranking)
const searchResults = await search_apis({ 
  query: "payment", 
  page: 1, 
  limit: 20 
});
// Note: Smart search shows provider APIs first + newest versions first within same relevance!

// Phase 2: Basic Evaluation (Get summaries for promising APIs)
const stripeInfo = await get_api_summary({ api_id: "stripe.com" });
const paypalInfo = await get_api_summary({ api_id: "paypal.com" });

// Phase 3: Detailed Analysis (Only for chosen API)
const endpoints = await get_endpoints({ 
  api_id: "stripe.com", 
  page: 1, 
  limit: 30 
});

// Get specific endpoint details for implementation
const paymentEndpoint = await get_endpoint_details({
  api_id: "stripe.com",
  method: "POST", 
  path: "/v1/charges"
});

// Get schemas and examples for coding
const schemas = await get_endpoint_schema({
  api_id: "stripe.com",
  method: "POST", 
  path: "/v1/charges"
});

const examples = await get_endpoint_examples({
  api_id: "stripe.com",
  method: "POST", 
  path: "/v1/charges"
});

📋 Efficient Resource Access

// Get directory overview (recommended starting point)
const summary = await readResource("openapi://apis/summary");

// Browse APIs in pages (50 per page)
const page1 = await readResource("openapi://apis/page/1");
const page2 = await readResource("openapi://apis/page/2");

// ⚠️ Avoid this - returns massive data
// const allApis = await list_all_apis(); // Can saturate context!

🎯 Smart Prompt Usage

// Best practice: Use api_discovery prompt for any use case
// Prompt: api_discovery  
// Arguments: { 
//   use_case: "send emails", 
//   requirements: "free tier available, good documentation" 
// }

// The prompt automatically guides through:
// 1. Efficient search with pagination
// 2. API summaries for comparison  
// 3. Progressive endpoint discovery
// 4. Implementation details only when needed

// Integration guide with progressive approach
// Prompt: api_integration_guide
// Arguments: { 
//   api_name: "Gmail API", 
//   programming_language: "JavaScript",
//   use_case: "send automated notifications"
// }

Legacy Tools (Use with Caution)

// These work but can consume lots of context:
const metrics = await get_metrics();
const providerStats = await get_provider_stats({ provider: "amazonaws.com" });
const popularApis = await get_popular_apis({ limit: 10 });

🏗️ Architecture

The server uses a modular, context-optimized architecture:

Triple-Source API Client: Handles communication with APIs.guru, secondary APIs, and custom imported specs
Enhanced Dual-Source Routing: Intelligent API resolution with custom-first precedence and fallback handling
Custom Spec Management: Complete import, storage, and lifecycle management for user-provided OpenAPI specs
Context-Aware Security Scanner: Intelligent security analysis with legitimate pattern recognition
Flag-Based Cache Invalidation: Automatic cross-process cache synchronization using filesystem flags
Persistent Cache Manager: Implements 24-hour TTL filesystem caching with real-time invalidation
CLI Interface: Full-featured command-line tool with interactive wizards and batch operations
Tool Generator: Creates MCP tools with pagination and context limits
Resource Handler: Manages paginated resource streaming (20 pages of 50 APIs each)
Progressive Discovery: Smart workflow guides preventing context saturation
Prompt System: 22 context-aware prompts using efficient discovery patterns
Cache Management: 5 tools for cache inspection and maintenance

New in v1.3.0

Hybrid CLI/MCP Architecture

The application now operates in dual mode:

CLI Mode: When arguments are provided, runs as a command-line tool for spec management
MCP Mode: When no arguments are provided, runs as an MCP server for Claude Desktop

# CLI Mode - Import management
openapi-directory-mcp --import ./api.yaml --name my-api --version v1

# MCP Mode - Service for Claude Desktop  
openapi-directory-mcp  # Starts MCP server

Enhanced API Client Architecture

DualSourceClient
├── Custom API Detection & Routing
├── Parameter Pattern Recognition  
├── Fallback Chain Management
└── Cache-Aware Resolution

Custom Provider Handling:
  provider="custom" + service="APIName" 
  → Routes to: customClient.getAPI("custom", "APIName")
  → Bypasses standard provider:service:version pattern

⚡ Performance

Metric	Value
Cold Start	< 2 seconds
Cache Hit	< 50ms response time
Cache Miss	< 500ms response time
Memory	< 100MB steady state
Context Usage	🎯 95% reduction vs traditional approaches
API Discovery	Explore 100+ APIs before context limits
Pagination	20-50 results per request (configurable)

Development

Prerequisites

Node.js >= 18.0.0
npm or yarn

Setup

git clone https://github.com/rawveg/openapi-directory-mcp.git
cd openapi-directory-mcp
npm install

Development Workflow

# Build the project
npm run build

# Run locally for testing
node dist/index.js

# Run tests
npm test
npm run test:coverage

# Development with auto-rebuild
npm run dev

# Lint code
npm run lint
npm run lint:fix

# Run pre-flight checks (recommended before pushing)
npm run preflight

Pre-flight Checks

This project includes a comprehensive pre-flight check system that catches common issues before they reach CI/CD:

# Run all pre-flight checks
npm run preflight

Pre-flight checks include:

Build Output - Ensures project is built
Tool Exposure - Validates all tool files are exposed (auto-adjusts to file count)
Prompt Exposure - Validates all prompt files are exposed (auto-adjusts to file count)
Mock Validation - Ensures test mocks implement required methods
TypeScript - Validates TypeScript compilation
ESLint - Validates code style and quality

Benefits:

⚡ Fast Failure - Catches issues in seconds instead of minutes
💰 Cost Savings - Avoids running expensive CI/CD for doomed builds
🎯 Specific Errors - Provides exact fix instructions
🔄 Self-Adjusting - No hardcoded counts, derives from filesystem

📚 Full Pre-flight Documentation

Git Hooks Setup

For automatic pre-push validation:

# Install git hooks
./scripts/install-hooks.sh

# This installs:
# - pre-push: Runs pre-flight checks before pushing

To bypass hooks in emergencies (not recommended):

git push --no-verify

Automated Release Process

This project uses an automated release workflow triggered by version tags:

Creating a Release

Ensure main branch is ready:

# Make sure you're on main and up to date
git checkout main
git pull origin main

# Ensure all tests pass
npm run validate

Update version and create tag:

# Update version in package.json (choose one)
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0  
npm version major  # 1.0.0 -> 2.0.0

# Or for pre-releases
npm version prerelease --preid=beta  # 1.0.0 -> 1.0.1-beta.0

Push tag to trigger release:

# Push the tag (this triggers the automated workflow)
git push origin --tags

# Also push the commit
git push origin main

CI/CD Pipeline

All pushes and pull requests run through our comprehensive CI/CD pipeline:

Pre-flight Checks (runs first, fails fast):
- Build validation
- Plugin exposure verification
- Mock completeness check
- TypeScript compilation
- Linting
Main Pipeline (only runs if pre-flight passes):
- Code quality checks
- Multi-node version testing (18, 20, 22)
- Plugin architecture validation
- Security scanning
- Test suites (unit, feature, integration, regression)

This staged approach saves CI/CD resources by catching common issues early.

What Happens Automatically

The GitHub Actions workflow will:

Pre-Release Validation:
- ✅ Verify version matches tag
- ✅ Check for changelog entry (optional)
- ✅ Run full test suite (lint, typecheck, tests)
- ✅ Build project and validate package contents
NPM Publishing:
- ✅ Build production version
- ✅ Configure NPM authentication
- ✅ Publish to NPM (stable or beta tag based on version)
- ✅ Verify publication and test installation
GitHub Release Creation:
- ✅ Generate changelog from commits
- ✅ Create GitHub release with installation instructions
- ✅ Upload build artifacts
- ✅ Mark as pre-release if beta/alpha/rc version
Post-Release Verification:
- ✅ Verify NPM package is accessible
- ✅ Verify GitHub release is created
- ✅ Update package badges

Manual Publishing (Fallback)

# Only use if automated process fails
npm login
npm run build
npm test
npm publish

Branch Protection

The main branch is protected and requires:

✅ Pull requests for all changes
✅ All CI checks to pass
✅ Up-to-date branches before merging
✅ No direct pushes to main

Release Requirements

All tests must pass
Version in package.json must match git tag
Optional but recommended: Update CHANGELOG.md
Required for NPM publishing: NPM_TOKEN secret configured

Local Testing with MCP Clients

After building, you can test with any MCP client using the absolute path:

# Get absolute path
pwd
# Example: /Users/yourname/projects/openapi-directory-mcp

# Use in client config:
node /Users/yourname/projects/openapi-directory-mcp/dist/index.js

Testing NPX Package Locally

To test the NPX installation before publishing:

# Create a local package
npm pack

# Test NPX installation from local tarball
npx ./openapi-directory-mcp-1.0.0.tgz

Option 1: Use Tarball Directly

# Claude Code with local tarball
claude mcp add openapi-directory -- npx -y ./openapi-directory-mcp-1.0.0.tgz

# Claude Desktop with local tarball
{
  "mcpServers": {
    "openapi-directory": {
      "command": "npx",
      "args": ["-y", "./openapi-directory-mcp-1.0.0.tgz"],
      "cwd": "/Users/yourname/projects/openapi-directory-mcp"
    }
  }
}

Option 2: Install Globally First

# Install globally for testing
npm install -g ./openapi-directory-mcp-1.0.0.tgz

# Find the installed binary path
which openapi-directory-mcp

# Use direct path (NPX still tries to fetch from registry)
claude mcp add openapi-directory -- /path/to/openapi-directory-mcp

# For Claude Desktop, use direct path
{
  "mcpServers": {
    "openapi-directory": {
      "command": "/path/to/openapi-directory-mcp"
    }
  }
}

# Uninstall when done testing
npm uninstall -g openapi-directory-mcp

Note: Even with global installation, npx openapi-directory-mcp will try to fetch from the NPM registry first and fail with 404. Use the direct binary path instead.

🔧 Plugin Architecture

This MCP server features a dual plugin architecture that enables zero-touch extensibility for both prompts and tools. All components are automatically discovered and loaded at startup from organized category folders.

Architecture Overview

Prompts Plugin System

src/prompts/
├── core-discovery/         # API discovery and analysis prompts
│   ├── api-discovery.ts
│   ├── api-integration-guide.ts
│   ├── api-comparison.ts
│   ├── authentication-guide.ts
│   ├── code-generation.ts
│   ├── api-documentation-analysis.ts
│   ├── troubleshooting-guide.ts
│   └── api-performance-analyzer.ts
├── action-oriented/        # Code generation and automation prompts
│   ├── retrofit-api-client.ts
│   ├── api-type-generator.ts
│   ├── api-test-suite.ts
│   ├── api-error-handler.ts
│   ├── api-migration-assistant.ts
│   ├── api-sdk-wrapper.ts
│   ├── api-webhook-scaffold.ts
│   ├── api-rate-limiter.ts
│   ├── api-graphql-wrapper.ts
│   └── api-batch-processor.ts
├── authentication/         # Authentication-focused prompts
│   ├── api-auth-implementation.ts
│   ├── api-auth-flow-generator.ts
│   ├── api-auth-middleware.ts
│   ├── api-auth-test-harness.ts
│   └── api-auth-debugger.ts
├── loader.ts              # Auto-discovery system
├── types.ts               # Prompt type definitions
└── templates.ts           # Main prompt interface

Tools Plugin System

src/tools/
├── api-discovery/          # Core API discovery tools
│   ├── get-providers.ts
│   ├── get-provider-services.ts
│   ├── list-all-apis.ts
│   └── get-metrics.ts
├── api-details/            # Detailed API information tools
│   ├── get-api.ts
│   ├── get-api-summary.ts
│   ├── get-openapi-spec.ts
│   ├── get-provider-stats.ts
│   └── search-apis.ts
├── endpoint-tools/         # API endpoint analysis tools
│   ├── get-endpoints.ts
│   ├── get-endpoint-details.ts
│   ├── get-endpoint-schema.ts
│   └── get-endpoint-examples.ts
├── cache-tools/           # Cache management tools
│   ├── cache-stats.ts
│   ├── cache-info.ts
│   ├── list-cache-keys.ts
│   ├── clear-cache.ts
│   └── clear-cache-key.ts
├── provider-tools/        # Provider-specific tools
│   └── get-provider-apis.ts
├── utility-tools/         # Analysis and utility tools
│   ├── analyze-api-categories.ts
│   ├── get-popular-apis.ts
│   └── get-recently-updated.ts
├── loader.ts             # Auto-discovery system
├── registry.ts           # Tool organization
├── handler.ts            # MCP integration
└── types.ts              # Tool type definitions

Adding New Prompts

Zero Development Overhead: Simply create a new .ts file in the appropriate category folder:

Create the prompt file:

// src/prompts/core-discovery/my-new-prompt.ts
import { PromptTemplate } from '../types.js';

export const prompt: PromptTemplate = {
  name: "my_new_prompt",
  description: "Description of what this prompt does",
  arguments: [
    {
      name: "api_name",
      description: "Name of the API to work with",
      required: true
    }
  ],
  generateMessages: (args) => [
    {
      role: "user",
      content: {
        type: "text",
        text: `Your prompt content here using ${args.api_name}`
      }
    }
  ]
};

export default prompt;

That's it! The system will:
- ✅ Automatically discover your prompt at startup
- ✅ Make it available as /openapi-directory:my_new_prompt
- ✅ Include it in the appropriate category
- ✅ Validate the prompt structure
- ✅ Handle all MCP protocol interactions

Adding New Tools

Zero Development Overhead: Simply create a new .ts file in the appropriate category folder:

Create the tool file:

// src/tools/api-discovery/my-new-tool.ts
import { z } from 'zod';
import { ToolDefinition, ToolContext } from '../types.js';

export const tool: ToolDefinition = {
  name: 'my_new_tool',
  description: 'Description of what this tool does',
  inputSchema: {
    type: 'object',
    properties: {
      api_name: {
        type: 'string',
        description: 'Name of the API to work with',
      },
    },
    required: ['api_name'],
  },
  async execute(args: any, context: ToolContext): Promise<any> {
    const schema = z.object({
      api_name: z.string(),
    });
    const params = schema.parse(args);
    
    // Your tool logic here using:
    // - context.apiClient for API operations
    // - context.cacheManager for cache operations
    
    return { result: `Processed ${params.api_name}` };
  }
};

export default tool;

That's it! The system will:
- ✅ Automatically discover your tool at startup
- ✅ Make it available through the MCP interface
- ✅ Include it in the appropriate category
- ✅ Validate the tool structure and parameters
- ✅ Handle all MCP protocol interactions

Adding New Categories

Create new folders under src/prompts/ or src/tools/ and add files inside:

# For prompts
mkdir src/prompts/my-category
# Add .ts files with prompt exports

# For tools  
mkdir src/tools/my-category
# Add .ts files with tool exports

The auto-loaders will discover and organize them automatically.

Plugin Architecture Benefits

Single Responsibility: Each component is ~15-70 lines
Zero Touch Extension: No code changes needed for new components
Organized: Clear folder-based categorization
Maintainable: Easy to find, edit, and test individual components
Scalable: Unlimited prompts/tools and categories supported
Type Safe: Full TypeScript validation and IntelliSense
Consistent: Same architecture pattern for both prompts and tools

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes (see Plugin Architecture above for adding prompts)
Add tests if needed
Submit a pull request

Plugin Contributions: Thanks to our dual plugin architecture, adding new prompts and tools is incredibly easy! Just follow the patterns above and submit a PR.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

❤️ Support This Project

If you find this MCP server valuable, especially if you're using it in a commercial context, please consider supporting its development through GitHub Sponsors.

Our Commitment

All sponsorship proceeds for this project are shared equally (50/50) with the APIs.guru project in recognition of their foundational work and the ongoing costs of maintaining the API infrastructure this project depends upon.

By sponsoring this project, you're not just supporting this MCP server - you're helping sustain the entire ecosystem that makes comprehensive API discovery possible. APIs.guru maintains over 3,000 API specifications and provides free API access to the developer community. Your support helps keep this invaluable resource available for everyone.

Support

Support Type	Link
Issues	GitHub Issues
Docs	API Reference
Examples	Examples Directory

🙏 Credits

Built with Model Context Protocol
API data from APIs.guru
Maintained by the OpenAPI Directory MCP team

Available Tools

22 tools

analyze_api_categoriesC

Analyze API distribution by categories

ParametersJSON Schema

Name	Required	Description	Default
`provider`	No	Optional provider filter

TDQS

C2.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose all behavioral traits. It only states 'analyze', implying a read operation, but omits details on side effects, data sources, rate limits, or output shape. Minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence with no wasted words, but it is overly minimal. While concise, it lacks sufficient detail to be informative, so it does not earn the highest score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, so the description should explain what the return value represents (e.g., a mapping of categories to counts). It does not. Given the low complexity, the description is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single optional parameter 'provider', which the schema already describes as 'Optional provider filter'. The description adds no additional semantics, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the verb 'analyze' and resource 'API distribution by categories', but the phrase 'distribution by categories' is ambiguous. It is unclear how this differs from sibling tools like get_popular_apis or get_api_summary, which also involve aggregated data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternative tools. There are many sibling tools with similar verbs (e.g., search, list, get), and no context is given about when categorization analysis is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cache_infoB

Get cache configuration and settings

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must bear the full burden of behavioral disclosure. It states 'Get' implying a read-only operation, but does not explicitly confirm idempotency, side-effect freedom, or rate limits. For a simple read tool, this is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that captures the tool's purpose without unnecessary words. It is front-loaded and efficient, earning its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (no parameters, no output schema) and the presence of many sibling tools, the description is minimally adequate. It states the purpose but omits details like the nature of the configuration (e.g., plain text, JSON structure) and does not confirm that it is safe to call. A more complete description would include a note on read-only behavior or typical response contents.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so parameter semantics are inherently clear. The schema coverage is 100% by default, and the description adds no extra parameter info because none is needed. This meets the baseline expectation for parameterless tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get cache configuration and settings' clearly specifies the action and resource. It distinguishes from sibling tools like 'cache_stats' (which returns statistics) and 'clear_cache' (which mutates state). However, it could be more precise about what specific configuration aspects are returned.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The purpose is implied, but there is no mention of prerequisites, when-not to use it, or comparisons to sibling tools like 'cache_stats' or 'list_cache_keys'. A brief note on context would improve clarity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cache_statsC

Get cache statistics and information

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states 'get cache statistics and information' without indicating whether the operation is safe (read-only), has side effects, or requires any prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (one short phrase), but while brevity is positive, it sacrifices useful detail. It is front-loaded but lacks substance to fully inform an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of parameters, output schema, and annotations, plus the presence of multiple sibling tools, the description is incomplete. It does not clarify what statistics are provided, how they are formatted, or how this tool compares to similar ones like 'cache_info'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has zero parameters with 100% coverage, so no parameter information is needed. The baseline score of 3 applies as the description adds nothing beyond what the schema already conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves cache statistics and information, using a specific verb and resource. However, it does not differentiate from the sibling tool 'cache_info' which likely has a similar purpose, leaving potential ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'cache_info' or 'list_cache_keys'. The description provides no context that helps an agent decide which sibling tool to invoke.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

clear_cacheC

Clear all cache entries

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility. It only states 'Clear all cache entries' without explaining consequences like performance impact, irreversibility, or scope. This is insufficient for a potentially destructive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (three words) but lacks necessary detail that would make it truly helpful. While it earns its place, it sacrifices completeness for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of sibling tools like 'clear_cache_key', 'cache_info', and 'cache_stats', the description should clarify the scope and effect of clearing all cache. Without this, an agent cannot distinguish or anticipate the tool's broad impact.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description does not need to add parameter context. The schema already covers everything trivially, and the description is consistent with no-op parameter list.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Clear' and resource 'all cache entries', making the action unambiguous. However, it does not differentiate from sibling tools like 'clear_cache_key', which also clears cache but for a specific key.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as 'clear_cache_key', 'cache_info', or 'cache_stats'. There is no mention of prerequisites, effects, or typical scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

clear_cache_keyC

Clear a specific cache key

ParametersJSON Schema

Name	Required	Description	Default
`key`	Yes	The cache key to clear

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only states 'clear' without disclosing behavior details such as immediate effect, required permissions, or side effects. Minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words. It is appropriately concise for a simple tool, though could include more detail without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple operation and one parameter, the description is somewhat complete but lacks behavioral context and does not leverage sibling tool contrasts. Could be more informative.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single parameter 'key' described. The description adds no extra meaning beyond the schema, meeting the baseline of 3 for a simple parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('clear') and the resource ('a specific cache key'), which is specific. However, it does not explicitly distinguish from sibling tools like 'clear_cache', which might clear all cache, leaving some ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., 'clear_cache') or when not to use it. The description only implies usage for clearing a single key but provides no context for decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_apiC

Get detailed information about a specific API

ParametersJSON Schema

Name	Required	Description
`provider`	Yes	Provider name (e.g., "googleapis.com", "azure.com")
`api`	Yes	API version (e.g., "v3", "2.0")
`service`	No	Service name (optional, required for some APIs)

TDQS

C2.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and the description only states 'Get detailed information' without disclosing behavioral traits such as read-only nature, authentication requirements, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is short but could be more informative; does not fully earn its place as it omits necessary details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 3 parameters and 20 sibling tools, the description is too minimal. It does not provide enough context for an agent to use the tool correctly or select it over alternatives.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description does not need to add parameter info. It adds no extra meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

Describes verb and resource ('Get detailed information about a specific API') but lacks specificity on what 'detailed information' includes, failing to distinguish from siblings like get_api_summary or get_endpoint_details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. With many sibling tools performing similar functions, the absence of selection criteria is a significant gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_api_summaryA

Get basic information about a specific API without endpoint details

ParametersJSON Schema

Name	Required	Description	Default
`api_id`	Yes	API identifier (e.g., "googleapis.com:admin", "github.com")

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It mentions that the tool returns basic information without endpoint details, but it does not describe what 'basic information' includes (e.g., name, description, version), whether it is read-only, authentication requirements, rate limits, or any side effects. This lack of detail leaves an AI with insufficient understanding of the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that is front-loaded with the verb and clearly conveys the main purpose. No unnecessary words or information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of an output schema and annotations, the description should compensate by explaining the return value. It only states 'basic information' which is vague. For a tool that retrieves data, the description is incomplete without specifying what fields or structure the response contains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'api_id' is fully described in the schema with an example. The description adds no additional meaning beyond the schema, so it meets the baseline for high schema coverage (100%).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get basic information about a specific API without endpoint details'. It specifies the verb 'Get', the resource 'basic information about a specific API', and explicitly excludes endpoint details, which distinguishes it from siblings like 'get_api' or 'get_endpoints' that may include such details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear guidance on when to use this tool: when you want basic information without endpoint details. This implies it should be used for high-level overviews, while siblings like 'get_api' or 'get_endpoints' are more detailed. However, it does not explicitly mention when not to use it or name specific alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_endpoint_detailsC

Get detailed information about a specific API endpoint

ParametersJSON Schema

Name	Required	Description
`api_id`	Yes	API identifier (e.g., "googleapis.com:admin", "github.com")
`method`	Yes	HTTP method (GET, POST, PUT, PATCH, DELETE, etc.)
`path`	Yes	API endpoint path (e.g., "/users/{id}", "/posts")

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It implies a read operation ('get') but provides no additional context about performance, authentication needs, or what constitutes 'detailed information'. This is insufficient for a tool that likely returns a complex response.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is concise and front-loaded with the verb and resource. However, it is too brief and could include more context without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 required parameters and no output schema, the description is incomplete. It does not explain what 'detailed information' includes, any constraints (e.g., pagination, filtering), or the return format, leaving the agent with ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% coverage with clear parameter descriptions (api_id, method, path). The description adds no extra meaning beyond what the schema provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get detailed information about a specific API endpoint' clearly states the verb (get) and resource (endpoint details), distinguishing it from siblings like 'get_api' (whole API) and 'get_endpoint_schema' (schema only). However, 'detailed information' is vague compared to more specific sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives like 'get_endpoint_schema' or 'get_endpoint_examples'. The description does not specify context or exclusions, leaving the agent without decision support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_endpoint_examplesC

Get request and response examples for a specific API endpoint

ParametersJSON Schema

Name	Required	Description
`api_id`	Yes	API identifier (e.g., "googleapis.com:admin", "github.com")
`method`	Yes	HTTP method (GET, POST, PUT, PATCH, DELETE, etc.)
`path`	Yes	API endpoint path (e.g., "/users/{id}", "/posts")

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It does not disclose whether examples are pre-generated or fetched live, any authentication requirements, or potential rate limits. The simple 'get' implies read-only, but no further behavioral context is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no extraneous words. Efficiently conveys the core purpose. Could be slightly more descriptive (e.g., 'sample' instead of 'examples'), but still concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with 3 well-described parameters and no output schema, the description is adequate but minimal. It does not specify the output format (e.g., array of examples) or any ordering, which would be helpful for a complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with clear descriptions for each parameter (api_id, method, path). The tool description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves request and response examples for a specific API endpoint. It is a specific verb-noun pair that distinguishes it from sibling tools like get_endpoint_schema or get_endpoint_details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. For example, it does not contrast with get_endpoint_schema (which returns the full schema) or get_endpoint_details (which may return other metadata). The agent is left to infer usage from the tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_endpointsA

Get a paginated list of endpoints for a specific API with minimal information

ParametersJSON Schema

Name	Required	Description
`api_id`	Yes	API identifier (e.g., "googleapis.com:admin", "github.com")
`page`	No	Page number (default: 1)
`limit`	No	Number of endpoints per page (default: 30, max: 100)
`tag`	No	Optional tag filter to show only endpoints with specific tag

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description partially covers behavior by stating it returns a paginated list. However, it omits details about authentication, error handling, or what 'minimal information' includes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded and concise, containing no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description does not explain the return structure of the paginated list (e.g., metadata like total count, next page), which is important for an agent to parse results. Given no output schema, more detail would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description adds no additional meaning to parameters. Baseline of 3 is appropriate as schema already documents all four parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets a paginated list of endpoints for a specific API with minimal information, differentiating it from siblings like get_endpoint_details which provide more detail.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance is provided. The description does not direct the agent to alternatives like get_endpoint_details for detailed endpoint info or get_api for overall API info.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_endpoint_schemaB

Get request and response schemas for a specific API endpoint

ParametersJSON Schema

Name	Required	Description
`api_id`	Yes	API identifier (e.g., "googleapis.com:admin", "github.com")
`method`	Yes	HTTP method (GET, POST, PUT, PATCH, DELETE, etc.)
`path`	Yes	API endpoint path (e.g., "/users/{id}", "/posts")

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does not disclose any behavioral traits such as read-only nature, permission requirements, rate limits, or side effects. The description merely states what it does, not how it behaves.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that front-loads the key information. It is efficient, though it could provide slightly more context without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and full schema coverage, the description is minimally adequate. However, with no output schema and many siblings, it lacks completeness in terms of when to select this tool over others and what the output looks like.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents all three parameters. The description adds no further meaning beyond 'Get request and response schemas,' which is consistent but not enhancing. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves both request and response schemas for a specific endpoint, using a specific verb+resource structure. This distinguishes it from siblings like 'get_endpoints' (which lists endpoints) and 'get_endpoint_details' (which may provide other details).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. With many sibling tools, an agent would benefit from explicit usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_metricsB

Get statistics and metrics about the API directory

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description should disclose behavior like read-only nature or required auth. It only says 'get', which implies read, but does not explicitly state safety or other traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words. Information density is high for the content provided.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless tool with no output schema and no annotations, the description is insufficient. Agents need to know what specific metrics are returned (e.g., counts, trends) to decide if this tool fits.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and schema coverage is 100%. Per the rubric, baseline is 4; the description adds no param info but is not needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves statistics and metrics about the API directory. It distinguishes from siblings like get_provider_stats or cache_stats by implying overall directory metrics, though more specificity would improve clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as get_provider_stats or get_popular_apis. The description offers no context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_openapi_specB

Get the OpenAPI specification for a specific API

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes	URL to the OpenAPI specification (JSON or YAML)

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It does not mention that this is a read-only network fetch, whether caching occurs, or any potential side effects. The minimal description forces the agent to infer safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no extraneous words. However, it sacrifices depth for brevity; a bit more context could be added without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one parameter, no output schema), so the description is minimally adequate. However, it omits details like whether the specification is fetched live or cached, and what the response format is (JSON/YAML object or string).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description for the 'url' parameter is already clear ('URL to the OpenAPI specification (JSON or YAML)'). The tool description adds no additional meaning beyond the schema. With 100% schema coverage, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Get') and the resource ('OpenAPI specification for a specific API'). It distinguishes itself from sibling tools like get_api (which likely returns API metadata) and get_endpoint_details (specific endpoints) by targeting the raw specification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as get_api_summary or get_endpoint_schema. It does not mention when not to use it or any prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_popular_apisC

Get the most popular APIs based on various metrics

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of APIs to return (default: 20)

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full responsibility for behavioral disclosure. It only states it 'gets' data, implying a read operation, but does not confirm idempotency, rate limits, or if authentication is needed. The metric calculation method is undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no redundant words. It could be slightly expanded to include key behavioral details without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and the presence of 19 sibling tools, the description fails to provide sufficient context. The agent does not know what data is returned (e.g., full API objects vs. names) or how popularity is measured, making it hard to choose confidently among similar tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% coverage for the single parameter (limit with description and default). The description adds no additional semantics beyond the schema, so it meets the baseline for well-documented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves 'most popular APIs' using a verb+resource pattern. It distinguishes from siblings like get_api (single API) and search_apis (filtered search) by focusing on popularity. However, 'various metrics' is vague, leaving the agent uncertain about what drives popularity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. It does not mention that this tool is for discovering trending APIs, nor does it advise against using it for specific API lookups. The agent must infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_provider_apisB

List all APIs for a specific provider

ParametersJSON Schema

Name	Required	Description	Default
`provider`	Yes	Provider name (e.g., "googleapis.com", "azure.com")

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. The description only states the basic function and does not mention any behavioral traits such as output format, pagination, rate limits, or whether authentication is required. This is insufficient for a read operation without annotation safety hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no wasted words. It is appropriately sized for a simple tool with one parameter, though it could benefit from slight expansion for completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (one required param, no output schema), the description provides the basic function. However, it lacks details about the return value (e.g., list of API names or full objects) and any filtering behavior, which would help the agent fully understand the output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add any meaning beyond the schema; it essentially restates the parameter purpose. The schema already describes the 'provider' parameter adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'List all APIs' and the specific resource 'for a specific provider'. This distinguishes it from sibling tools like 'get_providers' which lists providers, and 'list_all_apis' which lists all APIs without provider filter.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not specify any prerequisites, context, or exclusions, leaving the agent to infer usage solely from the tool name and schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_providersB

List all API providers in the directory

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.3/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations and a minimal description, there is no disclosure of behavioral traits like pagination, rate limits, data freshness, or whether the list is cached. The description fails to inform the agent about important runtime behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the tool's purpose at a glance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the one-sentence description is adequate but misses opportunities to explain output format, sorting, or differentiation from sibling tools like get_api_summary or get_provider_apis.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters, so the description correctly implies no parameters are needed. Schema coverage is 100%, and the description adds no additional parameter semantics, which is acceptable given the trivial parameter set.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (List), the resource (all API providers), and the scope (in the directory). It effectively distinguishes from sibling tools like get_provider_apis which lists APIs for a specific provider.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as get_provider_stats or get_provider_services. The description lacks context for an agent to decide between this and similar list tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_provider_servicesB

List all services for a specific provider

ParametersJSON Schema

Name	Required	Description	Default
`provider`	Yes	Provider name (e.g., "googleapis.com", "azure.com")

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description only states purpose without disclosing behavioral traits like pagination, rate limits, or response format. Full burden falls on description, which is minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no fluff, front-loaded with verb and resource. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description is adequate but lacks details about return values or limitations. Could be improved with example or mention of scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already describes the provider parameter. The description adds no additional meaning beyond the schema, meeting baseline expectations but not exceeding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'List' and resource 'services' with constraint 'for a specific provider', clearly distinguishing from siblings like get_provider_apis and get_providers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as get_provider_apis or get_providers. Agent is left to infer from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_provider_statsC

Get statistics for a specific provider

ParametersJSON Schema

Name	Required	Description	Default
`provider`	Yes	Provider name (e.g., "googleapis.com", "azure.com")

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must disclose behavioral traits. It only states 'Get statistics' without mentioning read-only nature, potential side effects, authentication needs, or what statistics are returned. This is insufficient for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words. It is appropriately sized for a simple tool with one parameter, though it could be slightly more informative without sacrificing brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and annotations, the description is incomplete. It does not explain what statistics are returned, any filtering capabilities, or whether it aggregates data across time periods. The tool is simple, but the description misses key contextual information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds no value beyond the schema's parameter description. The parameter is already well-described in the schema with an example. The tool description does not enhance parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves statistics for a provider. It uses a specific verb ('Get') and resource ('statistics for a specific provider'). However, it does not differentiate from sibling tools like 'get_providers' or 'get_provider_apis', which could also return aggregated data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool over alternatives. The description lacks any when-to-use, when-not-to-use, or comparison with sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_recently_updatedC

Get recently updated APIs

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of APIs to return (default: 10)

TDQS

C2.6/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, and the description does not disclose behavioral traits like ordering, definition of 'recently', authentication requirements, or rate limits. The description merely repeats the name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise at four words, but under-specified for effective use. Every word is necessary but insufficient for full comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and multiple sibling tools, the description fails to provide necessary context to distinguish from similar tools or clarify the scope of 'recently'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with the limit parameter already described. The description adds no extra semantics beyond the schema, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Get recently updated APIs', specifying verb and resource. It distinguishes from siblings like list_all_apis and search_apis by implying a focus on recent updates, but could be more explicit about sorting criteria.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives such as list_all_apis or search_apis. No prerequisites or context provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_all_apisA

List all APIs in the directory with metadata

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Only states it lists all APIs with metadata, but does not disclose behavior such as pagination, sorting, or limits. Insufficient for a complete understanding.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One clear sentence with no wasted words. Front-loaded with verb and object. Efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no parameters, the description is somewhat complete for a simple list operation. However, with many sibling tools, more context on output structure or ordering would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%. The description adds 'with metadata' hinting at output but not about parameters. Baseline 4 for zero parameters is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states verb 'List' and object 'all APIs in the directory' with added detail 'with metadata'. Distinguishes from sibling tools like get_api (single) and search_apis (filtered).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like search_apis or get_api. The description is minimal with no context on appropriate use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_cache_keysB

List all cache keys

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It only implies a read operation via 'list' but does not disclose potential costs, side effects, or limitations. No non-obvious behaviors are mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that efficiently communicates the core functionality without extraneous detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and annotations, the description is incomplete. It does not explain what 'cache keys' are, the format of the output, or whether pagination exists. For a tool with no parameters, this is insufficient context for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and schema coverage is 100%, so no parameter information is needed. The description does not add parameter meaning, but that is not necessary here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'List all cache keys' uses a specific verb ('list') and a clear resource ('cache keys'), making the tool's purpose unambiguous. It effectively distinguishes from sibling tools like 'clear_cache_key' or 'cache_info'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description does not mention any context, prerequisites, or exclusions, leaving the agent without direction for appropriate invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_apisA

Search for APIs by name, description, provider, or keywords with pagination support

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Search query string
`provider`	No	Optional provider filter
`page`	No	Page number (default: 1)
`limit`	No	Number of results per page (default: 20, max: 50)

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It mentions pagination support but lacks details on read-only nature, rate limits, or behavior for broad queries. Adequate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One succinct sentence that is front-loaded with key information. No unnecessary words or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description is brief. It covers purpose and pagination but lacks details on return format, sorting, or other behaviors. Not severely incomplete but could be more informative.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameter descriptions exist in the input schema. The description adds 'with pagination support' which aligns with page/limit parameters but does not provide additional meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Search for APIs' and specifies the resources (APIs) and scope (by name, description, provider, keywords). It distinguishes from sibling tools like 'get_api' and 'list_all_apis' which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for searching APIs but does not explicitly state when to use this tool versus alternatives like 'get_popular_apis' or 'get_provider_apis'. No exclusions or context for when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.2/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose. The many 'get_' tools target different aspects (API summary vs full details, endpoint details vs examples vs schemas, providers vs provider APIs vs provider services), and cache tools are separate. No two tools are ambiguous.

Naming Consistency4/5

Most tools follow a verb_noun pattern in snake_case, with 'get_' for retrieval. However, a few list operations use 'list_' (list_all_apis, list_cache_keys) instead of 'get_', introducing minor inconsistency. Otherwise naming is predictable.

Tool Count3/5

With 22 tools, the set is at the upper end of what is reasonable for an API directory server. The tools cover APIs, endpoints, providers, cache, and metrics, but the number feels slightly heavy, bordering on excessive for the domain.

Completeness4/5

The server provides comprehensive coverage for querying an API directory: listing, searching, detailed info on APIs and endpoints, provider stats, cache management, and metrics. A minor gap is the lack of a dedicated tool to list API categories (only distribution analysis), but overall the surface is solid.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Orbit A
ai.buildwithorbit
Turn any task into the right API calls: discover, evaluate, and integrate public APIs.
Developer Tools API Testing
21
Apis Guru A
io.github.pipeworx-io
APIs.guru MCP — keyless directory of 2,500+ public APIs and their OpenAPI specs.
Developer Tools Documentation Access
352
Reqistry A
dev.reqistry
Discover, compare, and monitor 1,400+ APIs directly from your AI coding agent.
Developer Tools Search Monitoring
131
Zyla API Hub A
com.zylalabs
Discover and call 10,000+ production APIs from one MCP server. Pay-per-call billing for AI agents.
Developer Tools
82

Related MCP Servers

OpenAPI MCP Server
API Testing Documentation Access Developer Tools
teddy258
A
license
Not graded
quality
D
maintenance
Exposes OpenAPI specifications as MCP tools, enabling AI assistants to explore and understand API structures, endpoints, schemas, and documentation through semantic queries.
Updated 4 months ago (2026-05-18 05:35 UTC)
19
MIT
OpenAPI MCP Server
API Testing Documentation Access Developer Tools
abumalick
A
license
Not graded
quality
D
maintenance
Enables LLMs to explore and query OpenAPI specifications, allowing natural language interaction with API endpoints, parameters, request bodies, and response schemas from any OpenAPI 3.x spec.
Updated 9 months ago (2025-11-30 10:59 UTC)
20
MIT
mcp-swagger
awssam
A
license
A
quality
D
maintenance
Exposes Swagger/OpenAPI API documentation to AI models, enabling exploration, search, and interaction with endpoints, schemas, and execution of API calls.
Updated 5 months ago (2026-04-16 22:47 UTC)
14
13
2
MIT
Janus MCP
Documentation Access Developer Tools
DeanWard
A
license
Not graded
quality
D
maintenance
Enables AI assistants to understand and interact with OpenAPI specifications, providing deep insight into API structures for faster and more accurate API integration.
Updated a year ago (2025-09-03 15:27 UTC)
17
1
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rawveg/openapi-directory-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Table of Contents

Acknowledgments

Features

🎯 Context Optimization & Progressive Discovery

The Problem

Our Solution: 95% Context Reduction

Smart Prompts Guide You

🚀 Quick Start

Local Development Setup

Configuration for Local Development

Claude Desktop (Local)

Claude Code (Local)

Cursor (Local)

Windsurf (Local)

NPX Installation

Claude Desktop (NPX)

Claude Code (NPX)

Cursor (NPX)

Windsurf (NPX)

📁 Custom OpenAPI Specifications

✨ Key Features

🚀 Quick Start

Import a Custom Spec

Manage Custom Specs

🛡️ Security Scanning

Security Rules

Context-Aware Intelligence

Security Modes

📂 Storage Architecture

🔄 Triple-Source Architecture

🔧 CLI Reference

Import Commands

Management Commands

General Commands

💡 Usage Examples

Interactive Import Workflow

Direct Import Examples

Management Examples

🔌 Seamless Integration

Tools Integration

Prompts Integration

Resources Integration

🎯 Best Practices

Naming Conventions

Security Recommendations

Version Management

Storage Maintenance

🚨 Error Handling

Common Import Issues

Integrity Issues

🔧 Environment Configuration

⚡ Automatic Cache Invalidation

How It Works

Technical Benefits

🛠️ Available Tools

Core API Discovery Tools (Context Optimized)

Progressive Discovery Tools (Recommended)

Utility Tools

Cache Management Tools

📦 Available Resources

Context-Optimized Resources

Paginated API Resources

💡 Available Prompts (Context-Optimized)

Core Discovery & Analysis Prompts

Action-Oriented Code Generation Prompts

Authentication-Focused Prompts

Configuration

🧑‍💻 Example Usage

🎯 Progressive Discovery Workflow (Recommended)

📋 Efficient Resource Access

🎯 Smart Prompt Usage

Legacy Tools (Use with Caution)

🏗️ Architecture

New in v1.3.0

Hybrid CLI/MCP Architecture

Enhanced API Client Architecture

⚡ Performance

Development

Prerequisites

Setup