Tool Management - OpenAPI MCP Server

Tool System Overview

OpenAPI MCP Server automatically converts OpenAPI operations into MCP tools, enabling AI systems to interact with REST APIs through standardized interfaces. The tool system provides intelligent generation, filtering, and management capabilities.

🔄 Dynamic Generation

Automatically creates tools from OpenAPI specifications with intelligent naming and parameter mapping

🎯 Advanced Filtering

Filter tools by tags, resources, operations, or explicit lists to expose only what you need

📝 Smart Naming

Intelligent abbreviation system with ≤64 character limit and readable formats

⚡ Meta-Tools

Built-in API exploration and dynamic endpoint invocation capabilities

Tool Generation Process

Tools are automatically generated from OpenAPI operations using a sophisticated mapping process:

1. OpenAPI Parsing

The server parses the OpenAPI specification and identifies all available operations

# OpenAPI specification example
paths:
  /users:
    get:
      operationId: getUsers
      summary: List all users
      tags: [users]
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
    post:
      operationId: createUser
      summary: Create a new user
      tags: [users]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string

2. Tool ID Generation

Each operation gets a unique tool ID using the format METHOD::pathPart

# Examples of tool ID generation
GET /users                     → GET::users
POST /users                    → POST::users
GET /users/{id}                → GET::users__---id
PUT /api/v1/users/{id}/profile → PUT::api__v1__users__---id__profile

# Path encoding rules:
# - Double underscores (__) separate path segments
# - Triple dashes (---) indicate path parameters
# - Leading/trailing slashes are removed

3. Tool Name Generation

Human-readable names are generated with intelligent abbreviation for the 64-character limit

// Name generation priority:
// 1. operationId (if present)
// 2. summary (if operationId missing)  
// 3. Generated from method + path (fallback)

"getUsers" → "get-users"
"ServiceUsersManagementController_updateUser" → "svc-usrs-mgmt-upd-usr-a1b2"
"List all active user accounts" → "list-all-actv-usr-accnts"

4. Schema Mapping

Parameters and request bodies are mapped to MCP tool input schemas

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "description": "Maximum number of users to return"
    },
    "name": {
      "type": "string", 
      "description": "User's full name"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "User's email address"
    }
  },
  "required": ["name", "email"]
}

Tool ID System

The tool ID system provides a robust way to identify and reference tools, even with complex OpenAPI paths.

ID Format

Tool IDs follow the format: METHOD::pathPart

# Basic examples
GET::users                    # GET /users
POST::users                   # POST /users
DELETE::users__123            # DELETE /users/123

# Path parameters
GET::users__---id             # GET /users/{id}
PUT::users__---id__profile    # PUT /users/{id}/profile

# Complex paths
GET::api__v1__users__---userId__orders__---orderId__items
# Represents: GET /api/v1/users/{userId}/orders/{orderId}/items

Path Encoding Rules

Original	Encoded	Description
`/`	`__`	Path separators become double underscores
`{param}`	`---param`	Path parameters get triple dash prefix
`/api/v1/`	`api__v1`	Leading/trailing slashes removed
`//users//`	`users`	Multiple slashes collapsed

ID Parsing and Validation

import { parseToolId, isValidToolId } from "@lucid-spark/openapi-mcp-server";

// Parse tool ID back to method and path
const { method, path } = parseToolId("GET::api__v1__users__---id");
// Returns: { method: "GET", path: "/api/v1/users/{id}" }

// Validate tool ID format
const isValid = isValidToolId("POST::users");
// Returns: true

const isInvalid = isValidToolId("invalid-id");
// Returns: false

Tool Name Generation

Tool names must be ≤64 characters and follow the pattern [a-z0-9-]+. The system uses intelligent abbreviation to ensure compliance.

Name Generation Priority

operationId - If present in OpenAPI spec
summary - If operationId is missing
Generated name - From HTTP method and path as fallback

Abbreviation Process

1. Initial Sanitization

Convert to lowercase and replace non-alphanumeric characters with hyphens

"getUserDetails" → "getuserdetails"
"Service_Users_Management" → "service-users-management"

2. Word Splitting

Split on camelCase, underscores, hyphens, and number boundaries

"getUserDetails" → ["get", "user", "details"]
"apiV1Users" → ["api", "v1", "users"]

3. Common Word Removal

Remove common API terms like "controller", "service", "api", etc.

["user", "service", "controller"] → ["user"]
["api", "v1", "users"] → ["v1", "users"]

4. Standard Abbreviations

Apply standard abbreviations for common terms

"service" → "svc"
"management" → "mgmt"
"authentication" → "auth"
"configuration" → "config"

5. Vowel Removal

Remove vowels from words longer than 5 characters

"details" → "dtls"
"information" → "nfrmtn"
"administrator" → "dmn"

6. Hash Addition

Add 4-character hash if still too long or input was very long

"very-long-operation-name" → "very-lng-oprtn-nm-a1b2"

Disabling Abbreviation

You can disable abbreviation if you prefer full names (may cause errors with long names):

# CLI usage
npx @lucid-spark/openapi-mcp-server openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec ./api-spec.yaml \
  --disable-abbreviation

// Library usage
const server = new OpenAPIServer({
  // ... other config
  disableAbbreviation: true
});

Tool Filtering

Control which tools are generated from your OpenAPI specification using various filtering options.

Tools Mode

Choose how tools are loaded from your API specification:

🌟 All Mode (Default)

Load all tools from the OpenAPI spec, applying any specified filters

--tools all

⚡ Dynamic Mode

Load only meta-tools for API exploration and dynamic invocation

--tools dynamic

🎯 Explicit Mode

Load only tools explicitly listed with --tool options

--tools explicit --tool GET::users --tool POST::users

Filter Types

By Tool ID/Name

Include specific tools by their ID or name

--tool GET::users
--tool post-users
--tool "user-management"

By OpenAPI Tags

Include tools tagged with specific labels

--tag users
--tag public
--tag admin

By Resource Path

Include tools under specific resource paths

--resource users
--resource auth
--resource api/v1

By HTTP Method

Include tools for specific HTTP operations

--operation GET
--operation POST
--operation PUT

Filtering Examples

Read-only API Access

npx @lucid-spark/openapi-mcp-server openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec ./api-spec.yaml \
  --operation GET \
  --operation HEAD

User Management Only

npx @lucid-spark/openapi-mcp-server openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec ./api-spec.yaml \
  --tag users \
  --resource users

Specific Operations

npx @lucid-spark/openapi-mcp-server openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec ./api-spec.yaml \
  --tools explicit \
  --tool GET::users \
  --tool POST::users \
  --tool GET::users__---id

Public API Only

npx @lucid-spark/openapi-mcp-server openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec ./api-spec.yaml \
  --tag public \
  --tag external

Meta-Tools

Meta-tools provide dynamic API exploration and invocation capabilities, allowing you to interact with endpoints that weren't pre-generated as tools.

🔍 list-api-endpoints

Lists all available API endpoints with optional filtering

{
  "name": "list-api-endpoints",
  "arguments": {
    "tag": "users",
    "method": "GET",
    "path": "/users"
  }
}

Features:

Filter by OpenAPI tags
Filter by HTTP methods
Filter by path patterns
Returns tool IDs and descriptions

📋 get-api-endpoint-schema

Gets detailed schema information for a specific endpoint

{
  "name": "get-api-endpoint-schema",
  "arguments": {
    "toolId": "GET::users__---id"
  }
}

Returns:

Complete parameter schemas
Request body schemas
Response schemas
Security requirements

⚡ invoke-api-endpoint

Directly invokes any API endpoint dynamically

{
  "name": "invoke-api-endpoint",
  "arguments": {
    "toolId": "POST::users",
    "parameters": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

Capabilities:

Invoke any endpoint dynamically
Automatic parameter validation
Full authentication support
Error handling and reporting

When to Use Meta-Tools

🔍 API Discovery

Explore unfamiliar APIs without generating all tools upfront

📊 Large APIs

Work with APIs that have hundreds of endpoints efficiently

🧪 Testing

Test specific endpoints during development

🎯 Selective Usage

Use only specific operations without cluttering the tool list

Tool Management Best Practices

🎯 Filtering Strategy

Use --operation GET for read-only access
Filter by tags for logical grouping
Use explicit mode for precise control
Consider meta-tools for large APIs

📝 Naming Optimization

Use clear operationIds in OpenAPI specs
Keep names descriptive but concise
Disable abbreviation only when necessary
Test name generation with examples

⚡ Performance

Filter tools to reduce memory usage
Use dynamic mode for exploration
Monitor tool generation time
Cache large OpenAPI specifications

🔧 Development

Use debug mode to inspect tool generation
Validate tool IDs and names
Test filtering combinations
Document your filtering strategy

Tool Statistics and Monitoring

Monitor tool generation and usage with built-in statistics:

Server Statistics

// Get server statistics (library usage)
const server = new OpenAPIServer(config);
await server.start();

const stats = server.getStats();
console.log(stats);

// Example output:
{
  tools: {
    total: 47,
    endpointTools: 44,
    metaTools: 3
  },
  openapi: {
    version: "3.0.0",
    paths: 22,
    operations: 44
  },
  filtering: {
    applied: true,
    includedTags: ["users", "public"],
    includedOperations: ["GET", "POST"]
  }
}

Debug Logging

# Enable debug mode to see tool generation details
npx @lucid-spark/openapi-mcp-server openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec ./api-spec.yaml \
  --debug

# Example debug output:
# ✅ Loaded OpenAPI specification (3.0.0)
# 🔍 Found 44 operations across 22 paths
# 🎯 Applying filters: tags=[users], operations=[GET,POST]
# 📝 Generated tool: get-users (GET::users)
# 📝 Generated tool: create-user (POST::users)
# ✅ Generated 15 tools (12 endpoint + 3 meta)