logo

APILENS MCP Server

APILENS NPM

|

Model Context Protocol

I. Overview

APILENS is a unified Node.js CLI and MCP server that serves focused OpenAPI and Swagger documentation context to AI agents. Instead of loading a full OpenAPI file into an agent context window, APILENS exposes targeted MCP tools that retrieve only the endpoint, schema, auth, and validation details needed for the current task.

It is built for agentic coding workflows where an assistant needs to integrate with HTTP APIs precisely, quickly, and safely without manually parsing large OpenAPI documents.

1. What problem does it solve?

Large OpenAPI files are expensive for agents to read directly. They often contain hundreds of endpoints, nested schemas, references, auth rules, server definitions, and examples. APILENS turns that document into a focused tool layer so agents can:

  • Search endpoints by path, method, summary, description, operation ID, and tags.
  • Read exact request and response details for one endpoint.
  • Resolve nested $ref schemas before implementation.
  • Validate request payloads before sending or generating integration code.
  • Read API auth configuration without scanning the whole spec.

2. Core features

  • Unified CLI and MCP server: One executable can run setup commands or start the MCP stdio server.
  • OpenAPI JSON/YAML support: Specs are parsed and validated using @apidevtools/swagger-parser.
  • Focused endpoint lookup: find_endpoint and get_endpoint keep agent context small and relevant.
  • Schema intelligence: get_schema and search_schema expose component schemas with resolved references.
  • Request validation: validate_request checks generated JSON against endpoint request schemas.
  • Auth discovery: get_auth returns global security requirements and security schemes.
  • Agent provider setup: The CLI can configure Antigravity IDE, Claude Desktop, Codex, Cline, and Roo Cline.

3. MCP tools

| Tool | Purpose | | --- | --- | | summarize_openapi | Return API metadata, servers, path count, operation count, and schema count. | | list_endpoints | List all HTTP endpoints. | | find_endpoint | Search endpoints by path, method, operation ID, summary, description, and tags. | | get_endpoint | Return one endpoint with params, request body, responses, auth, servers, resolved refs, and examples. | | get_schema | Return a component schema by name with resolved refs. | | search_schema | Search schemas by name and content. | | validate_request | Validate JSON data against an endpoint request schema. | | get_auth | Return global security requirements and security schemes. |

4. Tech stack

II. Getting Started

Prerequisites

APILENS requires:

  • Runtime: Node.js >=20
  • Input: OpenAPI or Swagger spec in JSON/YAML format
  • Usage target: MCP-compatible agent client

Installation

Install from npm:

npm install -g @dev.sugar/apilens-mcp

Or build locally from source:

npm install
npm run build

The build outputs a unified executable:

  • dist/cli.js — APILENS CLI and MCP stdio server entrypoint

Configure MCP using the CLI

Print a config snippet:

apilens print-config

Run interactive multi-provider setup:

apilens setup --spec https://example.com/openapi.yaml

Configure all detected providers automatically:

apilens setup --yes --spec https://example.com/openapi.yaml

Configure specific providers:

apilens setup --provider antigravity --provider claude --provider codex --spec https://example.com/openapi.yaml

Supported providers include:

  • antigravity
  • claude
  • codex
  • cline_vscode
  • roo_cline_vscode
  • cline_cursor
  • roo_cline_cursor

Manual MCP configuration

Add APILENS to an MCP client configuration:

{
  "mcpServers": {
    "apilens": {
      "command": "apilens",
      "args": ["--mcp", "--spec", "https://example.com/openapi.yaml"],
      "env": {
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}

Restart the MCP client after updating the configuration.

Spec resolution order

When running in MCP mode, APILENS resolves the spec source in this order:

  1. --spec <path-or-url> in apilens --mcp args.
  2. OPENAPI_SPEC environment variable.

Tool calls intentionally do not accept a spec path override. Start a separate APILENS MCP server instance for a different OpenAPI document.

III. Typical Agent Workflow

For a request like "create a shipment", the agent can use a precise three-step workflow.

1. Find the matching endpoint

{
  "tool": "find_endpoint",
  "arguments": {
    "query": "create shipment"
  }
}

2. Read exact endpoint details

{
  "tool": "get_endpoint",
  "arguments": {
    "method": "POST",
    "path": "/shipments"
  }
}

APILENS returns parameters, request body, responses, auth, servers, resolved schemas, and generated examples.

3. Validate the generated request body

{
  "tool": "validate_request",
  "arguments": {
    "method": "POST",
    "path": "/shipments",
    "data": {
      "vehicleId": "abc"
    }
  }
}

This allows the agent to correct payload structure before implementing an integration or sending a request.

IV. MCP resources

The server also exposes metadata resources:

  • openapi://info — API info, version, and servers.
  • openapi://components — OpenAPI components object.
  • openapi://servers — server list.

Use tools for endpoint and schema tasks. Use resources for direct metadata reads.