How do I use swagger-mcp?

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., "@swagger-mcp Add the Petstore API from https://petstore3.swagger.io/api/v3/openapi.json" 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.

swagger-mcp

by yunhwane

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

swagger-mcp

An MCP (Model Context Protocol) server that reads Swagger/OpenAPI specs and lets MCP clients explore API schemas and descriptions through natural language.

The core idea: register a project once, and the whole team can query it conversationally — no need to re-upload specs every time.

Supported Clients

Client	MCP Support	STDIO	Streamable HTTP
Claude Desktop	O	O	O
Claude Code	O	O	O
Cursor	O	O	O
Gemini (Google)	O	—	O
ChatGPT (OpenAI)	X	—	—

Streamable HTTP mode is recommended for clients that only support URL-based connections (e.g., Gemini).

Related MCP server: swagger-mcp-server

Quick Start

1. Install & Build

git clone https://github.com/yunhwane/swagger-mcp.git
cd swagger-mcp
npm install
npm run build

2. Configure your MCP client

Two transport modes are available: STDIO (default) and Streamable HTTP.

Option A: STDIO (default)

Claude Desktop — edit claude_desktop_config.json:

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

Claude Code — add .mcp.json in your project root:

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

Option B: Streamable HTTP

Start the HTTP server separately, then point your client to the URL. This mode is ideal for development — tsx watch auto-restarts on code changes without requiring manual MCP reconnection.

# Start the server (dev mode with hot reload)
npm run dev:http

# Or production mode
npm run build && npm run start:http

Claude Code — add .mcp.json in your project root:

{
  "mcpServers": {
    "swagger-mcp": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Gemini CLI — edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "swagger-mcp": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

The HTTP server listens on port 3000 by default (override with PORT env var).

3. Try it with the Petstore API

Once connected, just ask your MCP client:

"Register the Petstore API from https://petstore3.swagger.io/api/v3/openapi.json and explore its endpoints."

Or walk through the drill-down workflow:

1. add_project        →  Register "petstore" with the spec URL
2. list_services      →  See registered services and their API groups
3. list_apis          →  Browse all endpoints for "petstore"
4. describe_api       →  "GET /pet/{petId}" → see parameters, request/response schemas
5. describe_component →  "#/components/schemas/Pet" → drill into a specific schema

Example Conversations

"Add the Petstore API from https://petstore3.swagger.io/api/v3/openapi.json."
"What endpoints are available for managing pets?"
"Describe the GET /pet/{petId} endpoint."
"What fields does the Pet schema have?"
"Compare the current spec against this new version URL."

Features

OpenAPI 3.0.x / 3.1.x support (JSON & YAML, URL or local file)
4-step drill-down: services → APIs → endpoint detail → component schemas
Shallow $ref resolution — keeps responses concise while letting the LLM decide which schemas to explore
Spec diff with breaking change detection (responses, requestBody, parameters, schemas)
Snapshot store — auto-saves normalized specs on registration and after diffs, enabling offline comparison (max 5 per project)
LRU spec cache (max 20 entries, 5 min TTL)
Project registry persisted to ~/.swagger-mcp/registry.json
Built-in help tool for discoverability

Tools (8)

Tool	Description	Inputs
`help`	Show available tools and recommended workflow	—
`add_project`	Register a new OpenAPI project (URL)	`projectId`, `name`, `source`
`list_projects`	List all registered projects	—
`list_services`	List registered services with their API groups (tags)	—
`list_apis`	List all API endpoints for a service	`serviceName`
`describe_api`	Get detailed info about a specific endpoint (parameters, request body, responses)	`serviceName`, `path`, `method`
`describe_component`	Look up component schemas by `$ref` paths	`serviceName`, `refs`
`diff_apis`	Compare saved snapshot (or registered spec) against a new source, with breaking change detection	`serviceName`, `newSource`

4-Step Drill-Down Pattern

The center tools (list_services → list_apis → describe_api → describe_component) use shallow resolution: endpoint schemas are expanded one level, but component $refs are preserved. This lets the LLM decide which schemas to drill into, keeping responses concise and navigable.

Core Concepts

Project

A reusable unit representing an API spec source. Each project has a projectId, name, and source URL. Project metadata is persisted to ~/.swagger-mcp/registry.json.

Example: "petstore" project pointing to https://petstore3.swagger.io/api/v3/openapi.json

Spec Cache

Parsed OpenAPI documents are cached in-memory (LRU, max 20 entries, 5-minute TTL) to avoid re-fetching on every query.

Snapshot Store

When a project is registered via add_project, the spec is automatically normalized and saved as a snapshot. Each call to diff_apis that detects changes also saves a new snapshot. Snapshots are stored in ~/.swagger-mcp/snapshots/<projectId>/ (max 5 per project, deduplicated by content hash).

Spec Diff

diff_apis compares the latest saved snapshot against a new spec source. If no snapshot exists, it falls back to fetching from the registered URL. The diff engine detects:

Endpoint additions, removals, and modifications
Parameter changes (type, required, location)
Response status code and media type changes (with breaking change flags)
RequestBody additions, removals, and schema changes
Schema property and $ref changes

Architecture

┌─────────────────────────────────────────────┐
│                MCP Client                    │
│   (Claude Desktop / Code / Cursor / Gemini)  │
└──────────────────┬──────────────────────────┘
                   │ MCP Protocol
                   │ (STDIO or Streamable HTTP)
┌──────────────────▼──────────────────────────┐
│              swagger-mcp Server              │
│                                              │
│  ┌────────────┐ ┌────────────┐ ┌─────────┐  │
│  │  Project   │ │   Center   │ │  Diff   │  │
│  │  Tools (2) │ │  Tools (4) │ │ Tool (1)│  │
│  └─────┬──────┘ └─────┬──────┘ └────┬────┘  │
│        │              │             │        │
│  ┌─────▼──────┐ ┌─────▼─────────────▼────┐  │
│  │  Registry  │ │      Spec Cache        │  │
│  │ (~/.swagger│ │    (in-memory LRU)     │  │
│  │  -mcp/)    │ │                        │  │
│  └────────────┘ └─────────┬──────────────┘  │
│                           │                  │
│                 ┌─────────▼──────────────┐   │
│                 │  Loader + Normalizer   │   │
│                 │  (fetch, parse,        │   │
│                 │   resolve $refs)       │   │
│                 └────────────────────────┘   │
└──────────────────────────────────────────────┘

Registry — stores project metadata, persists to disk
Loader — fetches OpenAPI specs from URLs or local files, parses JSON/YAML
Normalizer — resolves $ref references recursively with circular ref detection
Differ — computes structural diff between two normalized specs (endpoints, parameters, responses, requestBody, schemas)
Spec Cache — LRU in-memory cache for parsed OpenAPI documents
Snapshot Store — persists normalized specs to disk for reliable diff comparisons

Tech Stack

Runtime: Node.js 20+
Language: TypeScript (strict mode, noUncheckedIndexedAccess)
MCP SDK: @modelcontextprotocol/sdk
Validation: zod
Build: tsup (ESM-only, target node20)
Test: vitest

Development

npm run dev        # Run STDIO mode with tsx
npm run dev:http   # Run HTTP mode with tsx watch (auto-reload)
npm run build      # Build with tsup → dist/
npm run check      # TypeScript type check
npm run start:http # Run HTTP mode in production
npm test           # Run all tests (vitest)

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

TDD Workflow

This project follows the Red-Green-Refactor cycle:

RED — Write a failing test first (tests/ mirrors src/ structure)
GREEN — Write the minimum implementation to pass the test
REFACTOR — Clean up while keeping tests green

Always run npm run check && npm test before finishing a change.

Project Structure

src/
├── index.ts           # STDIO entry point
├── http.ts            # Streamable HTTP entry point
├── http-handler.ts    # HTTP request handler (session management, DNS rebinding protection)
├── server.ts          # Shared McpServer creation (tool registration)
├── registry.ts        # Project registry state management
├── loader.ts          # OpenAPI spec fetcher (URL/file, JSON/YAML)
├── normalizer.ts      # $ref resolution and spec normalization
├── differ.ts          # Spec diff engine (endpoints, responses, requestBody, schemas)
├── snapshot-store.ts  # Persistent snapshot storage for diff comparisons
├── spec-cache.ts      # In-memory LRU cache for parsed specs
├── types.ts           # TypeScript type definitions
└── tools/
    ├── project.ts     # add_project, list_projects
    ├── center.ts      # list_services, list_apis, describe_api, describe_component
    ├── diff.ts        # diff_apis
    └── help.ts        # help
tests/                 # Mirrors src/ structure (vitest)
  ├── tools/           # Tool unit tests
  ├── fixtures/        # Test OpenAPI specs (petstore variants)
  └── *.test.ts        # Unit tests for loader, normalizer, registry, etc.

License

MIT

Available Tools

9 tools

add_projectB

ParametersJSON Schema

Name	Required	Description
`name`	Yes	Display name
`source`	Yes	URL to OpenAPI spec
`projectId`	Yes	Unique project identifier

TDQS

B3.4/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 side effects or behavior. It only says 'Register a new OpenAPI service' without mentioning whether the operation is idempotent, what happens if a project with the same ID exists, or if any permissions are required. This lack of transparency is a significant gap for a write operation.

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 that effectively communicates the core purpose with minimal waste. It is appropriately sized for a simple creation tool.

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 write operation with no annotations and no output schema, the description needs to convey basic behavioral context like return value or side effects. It does not. While the schema covers parameter meaning, the overall context is incomplete for an agent to understand the full impact of invoking this tool.

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 input schema already provides clear descriptions for all three required parameters ('Display name', 'URL to OpenAPI spec', 'Unique project identifier'), achieving 100% schema description coverage. The description itself adds no additional parameter semantics, so the baseline score of 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 action ('Register') and the resource ('a new OpenAPI service'), making the tool's purpose immediately obvious. It also distinguishes itself from the sibling tools, which are mostly read-only operations like list_projects and describe_api.

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?

No explicit when-to-use guidance or alternatives are mentioned, but the verb 'Register' and the contrast with the read/diff sibling tools imply this is for creating a new project/service. The usage context is reasonable to infer, though not stated.

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

describe_apiC

Get detailed info about a specific API endpoint

ParametersJSON Schema

Name	Required	Description
`path`	Yes	API path (e.g. /pets/{petId})
`method`	Yes	HTTP method (e.g. get, post)
`serviceName`	Yes	Service name (projectId)

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 the full burden of behavioral disclosure. It indicates this is a read operation ('Get') but does not elaborate on what 'detailed info' includes, potential authentication needs, error conditions, or side effects. The behavior is under-specified.

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 clearly conveys the core purpose. It is appropriately front-loaded and contains no unnecessary words. However, it is brief to the point of missing valuable context.

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 annotations, output schema, and the presence of sibling describe tools, the description is incomplete. It fails to clarify what information is returned, how it differs from describe_component/describe_common_types, or any usage context. A more complete description would address these gaps.

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 input schema already provides descriptions for all three parameters (serviceName, path, method) with 100% coverage. The description's reference to 'specific API endpoint' adds minimal additional semantic value beyond the schema's parameter descriptions.

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's function: retrieving detailed information about a specific API endpoint. It uses a specific verb ('Get') and identifies the resource ('API endpoint'), but it does not explicitly distinguish it from sibling tools like describe_component or describe_common_types.

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 lacks any mention of appropriate contexts, prerequisites, or exclusions.

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

describe_common_typesB

Get common response schemas and shared types from components

ParametersJSON Schema

Name	Required	Description	Default
`serviceName`	Yes	Service name (projectId)

TDQS

B3.2/5.0

Behavior2/5

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

With no annotations, the description carries the full burden. It states only the action 'Get' and the resource, without disclosing response format, error behavior, or possible side effects. The vagueness of 'common' and 'shared' adds ambiguity.

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 with the action 'Get'. It contains no wasted words and is easy to parse quickly.

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 tool has a single parameter and no output schema, the description is under-specified. It doesn't explain what 'common' means, what the returned schemas look like, or how this differs from describe_component, leaving significant gaps for the agent.

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 describes serviceName as 'Service name (projectId)' with 100% coverage. The description adds no further semantic detail beyond the schema, so 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 uses a specific verb+resource pattern: 'Get common response schemas and shared types from components'. This clearly distinguishes the tool from siblings like describe_api and describe_component, which target different resources.

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 about when to use this tool versus alternatives. It doesn't mention exclusions or refer to sibling tools, leaving the agent to infer usage from the resource description alone.

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

describe_componentB

Look up component schemas by $ref paths

ParametersJSON Schema

Name	Required	Description	Default
`refs`	Yes	List of $ref paths (e.g. #/components/schemas/Pet)
`serviceName`	Yes	Service name (projectId)

TDQS

B3.3/5.0

Behavior2/5

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

With no annotations provided, the description must disclose behavioral traits, but it does not mention return format, error handling, or any side effects. It only states the lookup intent, leaving the agent with no information about what happens on success or failure.

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 uses every word effectively. It is front-loaded and direct, with no filler 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?

The tool is simple with two well-described parameters, but since there is no output schema and no annotations, the description should explain what the lookup returns or how it behaves. The current description only covers the basic purpose and misses usage context and behavioral details, making it minimally adequate but not complete.

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 covers 100% of the two parameters (serviceName and refs), so the baseline is 3. The description adds only a slight contextual hint with 'by $ref paths', but does not elaborate on parameter formats or relationships beyond what the schema already provides.

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 ('Look up'), the resource ('component schemas'), and the method ('by $ref paths'). It distinguishes this tool from siblings like describe_api and describe_common_types by focusing specifically on component schemas and $ref lookup.

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 gives no indication of when to use this tool versus alternatives such as describe_api or describe_common_types. It simply states what it does without providing context, prerequisites, or exclusions.

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

diff_apisB

Compare current spec of a registered service against a new source

ParametersJSON Schema

Name	Required	Description	Default
`newSource`	Yes	New spec source (URL or file path) to compare against
`serviceName`	Yes	Registered service name (projectId)

TDQS

B3.4/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 states the tool compares, but it doesn't disclose whether this is read-only, what the output format looks like, or any side effects. This is a significant gap for a tool that may interact with registered services.

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, efficient sentence that front-loads the action ('Compare') and includes the key objects (current spec, registered service, new source). No wasted words.

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?

Despite low complexity and full schema coverage, the description omits important context such as the expected return type (diff output?), error behavior, and whether the operation has side effects. Since no output schema exists, the description should explain the result of the comparison, but it doesn't.

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?

Both parameters are fully described in the schema (100% coverage): serviceName as the registered service name and newSource as the spec source. The description's phrasing ('registered service' and 'new source') aligns with the schema but adds no further meaning beyond what the schema already provides.

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 function: comparing a registered service's current spec against a new source. The specific verb 'compare' and references to 'registered service' and 'new source' distinguish it from sibling tools that list or describe resources.

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 context—when you need to compare specs before updating—but it doesn't explicitly state when to use it vs alternatives, nor does it mention prerequisite conditions like service existence or source accessibility. Sibling tools have different purposes, so the intended use is inferable but not explicitly guided.

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

helpA

Show available tools and recommended workflow

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

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

With no annotations, the description must carry the behavioral burden. 'Show' implies a read-only operation, but it does not explicitly state that no data is modified, nor describe the output format. For a simple help tool this is mostly sufficient, but lacks explicit side-effect disclosure.

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, front-loaded with the verb and resource. Every word earns its place, with no unnecessary details.

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

Completeness4/5

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

For a parameterless help tool with no output schema and simple behavior, the description provides enough context to understand what the tool does. It could optionally mention that it lists all tool names and suggests a usage order, but these are not essential for a tool of this simplicity.

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, making schema coverage trivially 100%. There is nothing to explain; the baseline of 4 is appropriate since no parameter information is needed beyond what the schema already shows.

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 uses the specific verb 'Show' with clear resources: 'available tools' and 'recommended workflow'. This distinguishes it from sibling tools that operate on projects, services, and APIs, making its purpose unmistakable.

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 when to use it—when you need to see what tools exist or how to proceed—but does not explicitly state exclusions or compare with alternatives. There is no mention of 'use this first' or 'use instead of X', so guidance is only implicit.

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

list_apisB

List APIs for a service (simplified)

ParametersJSON Schema

Name	Required	Description	Default
`serviceName`	Yes	Service name (projectId)

TDQS

B3.3/5.0

Behavior2/5

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It only states 'List APIs' without elaborating on permissions, return format, pagination, or the meaning of 'simplified'. Minimal behavioral transparency.

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 immediately conveys the core purpose. It has no filler or redundant content, and is appropriately sized for a simple list operation.

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 is mostly adequate for a simple list tool given the schema and lack of annotations, but the term 'simplified' introduces ambiguity about the response format. Without an output schema or further elaboration, the description feels incomplete regarding what exactly is listed.

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 covers 100% of parameter descriptions, including serviceName as 'Service name (projectId)'. The tool description adds no additional meaning to the parameter beyond what the schema already provides, so baseline 3 applies.

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 'List APIs for a service', which is a specific verb and resource. It distinguishes from sibling tools like list_services (lists services) and describe_api (describes a single API). The '(simplified)' qualifier does not obscure the intended action.

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. The description does not mention exclusions or when to prefer list_apis over describe_api or other siblings. Only the schema's required serviceName hints at usage, but that is not explicit guidance.

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

list_projectsC

List all registered services

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

C2.5/5.0

Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure, but it offers no details about output format, scope, authentication, or what 'registered services' means. The description does not go beyond the basic action and leaves behavioral expectations unstated.

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, but the brevity sacrifices important context and contributes to the ambiguity with sibling tools.

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 no-parameter, low-complexity list tool, the description is nearly minimal, but it is incomplete in context: it fails to clarify the relationship between 'projects' and 'services' and does nothing to distinguish itself from list_services. Without an output schema, the description should provide more context about the return value.

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 automatically satisfied. The description does not need to compensate for undocumented parameters because there are none.

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

Purpose2/5

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

The description states a clear action ('List all registered services') but the resource ('services') does not match the tool name ('projects'), and the sibling list_services likely duplicates this exact action. This mismatch and lack of differentiation make the purpose misleading rather than clear.

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?

There is no guidance on when to use this tool versus alternatives. It only provides a bare action phrase, leaving the agent to infer the appropriate context and compare against siblings like list_services on its own.

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

list_servicesA

List registered services with API groups

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.9/5.0

Behavior3/5

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

With no annotations provided, the description carries the full burden. 'List' implies a read-only operation, and 'with API groups' hints at return structure, but the description does not disclose pagination, ordering, permissions, or potential limitations. It is minimal but not misleading.

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 superfluous words. It efficiently conveys the tool's purpose and output grouping.

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 (0 params, no output schema), the description gives a high-level indication of the return value ('services with API groups') but lacks specifics about the structure or contents of each service. It is adequate but leaves some gaps for a complete understanding.

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% (empty schema). The baseline for 0 parameters is 4, and the description need not explain any parameters. It adds no parameter info, but none is needed.

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 registered services with API groups' uses a specific verb ('list') and resource ('services'), and adds a qualifier ('with API groups') that distinguishes it from sibling tools like list_apis and list_projects. This is a clear, actionable statement of the tool's function.

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 its use for retrieving services but does not explicitly state when to choose it over alternatives or when not to use it. The resource type provides implicit differentiation from sibling tools, but no explicit guidance is given.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

9 tool updatesv0.1.0Aug 9, 2026
- First observedadd_project
- First observeddescribe_api
- First observeddescribe_common_types
- First observeddescribe_component
- First observeddiff_apis
- First observedhelp
- First observedlist_apis
- First observedlist_projects
- First observedlist_services

Install Server

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

TDQS

B3.2/5.0

Disambiguation3/5

list_projects and list_services both list registered services, creating overlap, though descriptions distinguish them by detail. describe_component and describe_common_types both deal with component schemas, which could cause misselection. Other tools are clearly distinct.

Naming Consistency4/5

Most tools follow a verb_noun pattern in snake_case (add_project, list_projects, describe_api), but 'help' is a standalone verb and 'diff_apis' uses an unconventional verb. Minor deviations from an otherwise consistent style.

Tool Count5/5

With 9 tools, the set is well-scoped for managing OpenAPI services, fitting the ideal 3-15 range. Each tool addresses a specific aspect of the domain without bloat.

Completeness3/5

The set covers registration, listing, and detailed descriptions, but lacks update/delete operations for projects and a general component listing tool. These are notable gaps for a complete lifecycle, though core workflows are supported.

Maintenance

ActivityInactive

ResponsivenessNo issues

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

api-governance A
io.github.coderifts
API governance for AI agents. Detects breaking changes, scores blast radius, blocks unsafe calls.
API Testing Security Autonomous Agents
32
oasdiff A
io.github.oasdiff
Detect breaking changes, generate changelogs, diff, and validate OpenAPI specs.
API Testing Developer Tools CI/CD & DevOps
42
Orbit A
ai.buildwithorbit
Turn any task into the right API calls: discover, evaluate, and integrate public APIs.
Developer Tools API Testing
21
llmref A
org.llmref
Versioned documentation registry and semantic search for AI tools and coding assistants.
Documentation Access Search Developer Tools
42

Related MCP Servers

swaggbot
API Testing Developer Tools
TechBloom-ai
A
license
Not graded
quality
D
maintenance
Transforms Swagger/OpenAPI documented APIs into conversational interfaces, enabling natural language interaction with APIs through an MCP server for use with AI assistants.
Updated 6 months ago (2026-02-23 01:21 UTC)
4
MIT
swagger-mcp-server
API Testing Documentation Access
maohuihua123
A
license
Not graded
quality
D
maintenance
Enables natural language interaction with any Swagger/OpenAPI-defined API, allowing discovery, parameterized calls, and automated testing through large language models.
Updated a year ago (2025-05-19 09:47 UTC)
5
Apache 2.0
mcp-swagger-reader
API Testing Documentation Access Code Analysis
momei-LJM
F
license
A
quality
D
maintenance
Enables reading and parsing Swagger/OpenAPI specifications to list API endpoints, get detailed endpoint info, search APIs, and generate TypeScript types for request/response.
Updated 6 months ago (2026-03-05 03:25 UTC)
9
-
Swagger MCP
API Testing Documentation Access
yangyaofei
A
license
Not graded
quality
D
maintenance
Loads and queries OpenAPI/Swagger documents, providing tools to list APIs, get details, search endpoints, and manage schemas for efficient API exploration.
Updated a year ago (2025-07-11 17:38 UTC)
4
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/yunhwane/swagger-mcp'

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