Allows AI agents to explore and understand any API documented with Swagger/OpenAPI by providing tools to search endpoints, schemas, and auth details.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@swagger-mcp list endpoints for order management"
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.
A read-only Model Context Protocol server for navigating an OpenAPI / Swagger specification. It gives a coding agent tools to explore a large API's documentation — search endpoints, read parameters and schemas, inspect auth — without dumping the whole spec into context.
It never calls the described API. It only reads its documentation.
Works with any MCP-capable harness (Claude Code, Cursor, Cline, Windsurf, Zed, opencode, …) over stdio.
Add it to your MCP client config. No install step — npx fetches it on demand:
{
"mcpServers": {
"swagger-mcp": {
"command": "npx",
"args": ["-y", "@emreyc/swagger-mcp@latest"]
}
}
}Every tool takes a spec parameter — a URL (or local path) to a Swagger 2.0 or
OpenAPI 3.x document — so a single server can navigate any number of specs in one
session. Internal/localhost URLs (e.g. Spring Boot's
http://localhost:8080/v3/api-docs) are supported.
If you mostly work with one spec, set API_DOCS_URL as a default so spec can be
omitted:
{
"mcpServers": {
"swagger-mcp": {
"command": "npx",
"args": ["-y", "@emreyc/swagger-mcp@latest"],
"env": { "API_DOCS_URL": "https://api.example.com/swagger.json" }
}
}
}Specs are fetched lazily and cached per URL for the process lifetime.
Related MCP server: OpenAPI Schema Explorer
Designed for progressive disclosure — orient, then discover, then drill down — so the agent loads only what it needs.
Tool | Purpose |
| Title, version, servers, global security, counts. Start here. |
| Tags (logical groups) with endpoint counts. |
| Compact index of endpoints; optional |
| Substring search over path/summary/description/params. |
| Named schemas with one-line descriptions. |
| Substring search over schema names, fields, descriptions. |
| Full detail for one |
| Resolve one named schema. |
| Security schemes in full (OAuth2 flows, scopes, API-key locations). |
Every tool also accepts an optional spec argument (a spec URL or path); when
omitted it falls back to API_DOCS_URL.
Swagger 2.0 and OpenAPI 3.x are normalized into one consistent output shape.
Nested named schemas are shown as { "$schema": "Name" } markers — call
get_schema to expand them. This keeps every response bounded and is safe with
circular schemas.
npm install
npm run typecheck
npm test
npm run buildMIT
Top-level API metadata: title, version, description, servers, global security, and counts. Start here on an unfamiliar API.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | URL or local path of the OpenAPI/Swagger spec. Defaults to the server's configured API_DOCS_URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and openWorldHint=false. The description adds context by listing returned fields (title, version, etc.) and counts, which is valuable beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first lists contents, second provides usage recommendation. Every word is purposeful, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 1 optional parameter, strong annotations, and no output schema, the description adequately explains the output and usage. It covers all needed context for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. The description repeats the parameter info by mentioning 'Defaults to the server's configured API_DOCS_URL,' which is already in the schema's description. No additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves 'Top-level API metadata: title, version, description, servers, global security, and counts.' It distinguishes itself from siblings like get_endpoint or list_endpoints by focusing on the overarching API overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises 'Start here on an unfamiliar API,' providing clear usage context. It does not explicitly list when not to use or alternatives, but the sibling tools (e.g., get_auth, get_endpoint) cover other aspects, making the guidance adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full security schemes for the API (OAuth2 flows, scopes, API-key locations) plus the global security requirement.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | URL or local path of the OpenAPI/Swagger spec. Defaults to the server's configured API_DOCS_URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true; the description adds specifics about what is returned (OAuth2 flows, scopes, API-key locations, global security requirement), enhancing transparency beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is clear and front-loaded with the key output, containing no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with one optional parameter, the description sufficiently covers the return value; however, it could be more explicit about the output format, though not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'spec' has a description in both schema and description, with the description adding the default behavior ('Defaults to the server's configured API_DOCS_URL'), providing extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool returns 'Full security schemes for the API' including OAuth2 flows, scopes, and API-key locations, distinguishing it from sibling tools like get_api_overview or get_endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit usage guidance or alternatives are provided; the description implies when to use it but does not exclude other tools or give context on 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.
Full detail for one endpoint: parameters, request/response schemas, and required auth. Named schemas are shown by name — resolve them with get_schema.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Exact path as it appears in the spec, e.g. /pets/{id}. | |
| spec | No | URL or local path of the OpenAPI/Swagger spec. Defaults to the server's configured API_DOCS_URL. | |
| method | Yes | HTTP method, e.g. GET, POST. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds that named schemas are shown by name and need to be resolved separately, which is a key behavioral trait beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no unnecessary words. The first sentence front-loads the purpose, and the second provides a critical usage note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers the return content (parameters, schemas, auth) and schema resolution. It is sufficiently complete for a tool with 3 simple parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter descriptions are already clear. The description adds minimal extra value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides full detail for one endpoint, with specific verb and resource. It also differentiates from siblings by noting schema resolution via get_schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. While it hints at using get_schema for detailed schemas, it doesn't distinguish from sibling tools like list_endpoints or search_endpoints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve one named schema. Nested named schemas are shown as { "$schema": "Name" } markers — call get_schema again to expand them.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Schema name as shown by list_schemas. | |
| spec | No | URL or local path of the OpenAPI/Swagger spec. Defaults to the server's configured API_DOCS_URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows it's a safe read. The description adds behavioral context about nested schema markers and the need for recursive calls, which is beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the main action, and contains no unnecessary words. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the critical behavior about nested schema markers but does not detail error handling or response structure. For a simple read tool with annotations, this is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have descriptions in the input schema (100% coverage). The tool description does not add any extra meaning beyond what the schema already provides, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'resolve' and resource 'one named schema', clearly distinguishing it from sibling tools like list_schemas (list all) and search_schemas (search). It also adds unique behavior about nested schema markers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent to call get_schema again to expand nested schemas, providing a clear usage pattern. However, it does not mention when to use alternatives or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compact index of endpoints (method, path, summary, tags). Optionally filter by tag.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Only list endpoints with this tag. | |
| spec | No | URL or local path of the OpenAPI/Swagger spec. Defaults to the server's configured API_DOCS_URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the description adds context about return fields (method, path, summary, tags) but does not disclose additional behavioral traits like ordering, pagination, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with core concept ('Compact index of endpoints'), no redundant words. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description adequately explains the response format (method, path, summary, tags) and filtering. Could be improved by mentioning ordering or that it lists all endpoints when no tag is provided, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described in the schema. Description restates the tag parameter as 'optionally filter by tag', adding no new semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it provides a compact index of endpoints with method, path, summary, and tags, and optionally filters by tag. This distinguishes it from siblings like get_endpoint (single endpoint) and search_endpoints (search-based), making the purpose immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for quick overviews with optional tag filtering, but no explicit guidance on when to prefer this tool over siblings like search_endpoints or get_endpoint. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List named component/definition schemas with one-line descriptions.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | URL or local path of the OpenAPI/Swagger spec. Defaults to the server's configured API_DOCS_URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds minor value by clarifying the output format (one-line descriptions). It does not mention any side effects, but none are expected. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero wasted words. It efficiently conveys the tool's action and output form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 on pagination, the description does not explain whether the list is complete or paginated, nor the structure of the one-line descriptions. It is adequate for a simple list tool but leaves some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes the single parameter 'spec'. The tool description adds no further explanation of parameter semantics, so it meets the baseline for high coverage without adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'named component/definition schemas', and specifies that it provides 'one-line descriptions', which distinguishes it from 'get_schema' (full detail) and 'search_schemas' (filtered).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing schemas but does not explicitly state when to use it versus alternatives like 'search_schemas' or 'get_schema'. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the API's tags (logical groups) with descriptions and endpoint counts.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | URL or local path of the OpenAPI/Swagger spec. Defaults to the server's configured API_DOCS_URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds that it returns descriptions and endpoint counts, which is useful but minimal additional disclosure beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, 12 words, front-loaded with the verb and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately indicates the return type (descriptions and counts). For a simple list operation with 0 required parameters, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'spec' parameter already described well. The description adds no additional parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'tags', and the returned information ('descriptions and endpoint counts'). It distinguishes from sibling tools like list_endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 list_endpoints or get_api_overview. The description does not mention any prerequisites or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Substring search over endpoint path, summary, description, tags, and parameter names. Returns matches ranked by relevance.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | URL or local path of the OpenAPI/Swagger spec. Defaults to the server's configured API_DOCS_URL. | |
| query | Yes | Case-insensitive substring to match. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and openWorldHint=false, so the tool is safe and scoped. The description adds that it returns matches ranked by relevance, which is behavioral context beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. First sentence states the action and scope, second sentence states the output behavior. Information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and full parameter coverage, the description adequately covers search behavior and ranking. It could mention default for spec parameter (already in schema) or absence handling, but overall complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning by specifying the fields searched (path, summary, etc.), which is not in the parameter descriptions. This helps the agent understand the query parameter's effect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs substring search over endpoint path, summary, description, tags, and parameter names, and returns matches ranked by relevance. This distinguishes it from sibling tools like list_endpoints (no search) and search_schemas (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to find endpoints by substring), but does not explicitly state when not to use or provide alternatives. Sibling tool names provide some differentiation, but no direct guidance on choosing between similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Substring search over schema names, property names, and descriptions. Returns matches ranked by relevance.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | No | URL or local path of the OpenAPI/Swagger spec. Defaults to the server's configured API_DOCS_URL. | |
| query | Yes | Case-insensitive substring to match. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the description is not required to repeat that. The description adds that it performs substring search and returns ranked results, providing useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-loaded with key action and output. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description sufficiently covers the tool's purpose and output (ranked matches). Since there is no output schema, the description adequately explains return behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description mentions substring search but does not add significant new meaning beyond the schema descriptions (e.g., 'Case-insensitive substring to match').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs substring search over schema names, property names, and descriptions, and returns ranked matches. This distinguishes it from siblings like list_schemas and search_endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description describes what the tool does but provides no guidance on when to use it versus alternatives. It does not mention when not to use it or specify prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_api_overviewget_authget_endpointget_schemalist_endpointslist_schemaslist_tagssearch_endpointssearch_schemasEach tool has a clearly distinct purpose: API metadata, auth, endpoint details, schema resolution, listings of endpoints/schemas/tags, and searching. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_api_overview, list_endpoints, search_schemas), making them predictable and easy to understand.
With 9 tools, the set is well-scoped for an API exploration server. Each tool serves a necessary function without redundancy or unnecessary complexity.
The tool surface covers the full exploration workflow: overview, auth, listing endpoints/schemas/tags, detailed endpoint and schema retrieval, and substring search. No obvious gaps for the intended purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for AI access to Swagger by SmartBear.
Read-only MCP server over the APIs.io catalog — discover APIs, providers, tags & artifacts.
Guarded MCP server for agent-readable business truth, provenance, readiness, and discovery.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/emreycolakoglu/swagger-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
