사양을 읽고, API를 이해하고, 자신 있게 통합하세요.
English | 繁體中文
apifable은 AI가 TypeScript 프론트엔드 프로젝트에 API를 더 원활하게 통합할 수 있도록 돕는 MCP 서버입니다. API 구조를 쉽게 탐색하고, 엔드포인트를 검색하며, TypeScript 타입을 생성하여 AI 에이전트가 정확한 통합 코드를 작성하는 데 필요한 컨텍스트를 제공합니다.
Related MCP server: openapi-mcp-proxy
📦 AI용 API 컨텍스트 — AI가 API를 이해하고 작업하는 데 필요한 구조를 제공합니다.
📘 OpenAPI 3.0 / 3.1 지원 — 신뢰할 수 있는 정보원으로서 표준 사양과 함께 작동합니다.
🤖 AI 에이전트를 위한 MCP 서버 — Claude, Cursor, Windsurf에 연결하세요.
🔍 API 탐색 도구 — 엔드포인트를 탐색하고, 키워드로 검색하며, 전체 요청/응답 세부 정보를 검사합니다.
🏷️ TypeScript 타입 생성 — 프론트엔드 코드에서 바로 사용할 수 있는 TypeScript 타입 정의를 생성합니다.
apifable init을 실행하여 프로젝트 구성을 설정하세요:
npx apifable@latest init이 명령은 프로젝트 루트에 apifable.config.json을 생성합니다. 사양 경로를 팀과 공유할 수 있도록 이 구성 파일을 버전 관리 시스템에 커밋해야 합니다.
명령이 시작된 후, **수동 파일(Manual file)**과 원격 URL(Remote URL) 중에서 선택할 수 있습니다.
OpenAPI 사양이 이미 프로젝트 내에 있거나 사양 업데이트를 직접 관리하려는 경우 이 모드를 사용하세요.
init은 openapi.yaml과 같은 로컬 파일 경로를 묻습니다.
그런 다음 해당 경로에 OpenAPI 사양 파일을 수동으로 배치해야 합니다. 백엔드 API가 변경되면 해당 파일도 수동으로 업데이트해야 합니다.
OpenAPI 사양을 백엔드 API 문서에서 제공하는 OpenAPI 사양 엔드포인트와 같은 안정적인 원격 URL에서 가져올 수 있는 경우 이 모드를 사용하세요.
init은 먼저 https://api.example.com/openapi.yaml과 같은 원격 URL을 묻고, 그 다음 ./openapi.yaml과 같은 로컬 출력 경로를 묻습니다.
[!NOTE] 이 모드에서
init은 다운로드된 로컬 사양 경로를.gitignore에 자동으로 추가합니다. 이 파일은 원격 소스에서 새로 고쳐지도록 설계되었기 때문입니다.
그런 다음 다음 명령을 실행하여 원격 URL에서 로컬 경로로 OpenAPI 사양을 다운로드할 수 있습니다 (spec.url → spec.path). 사양이 변경될 때마다 다시 실행하여 새로 고치세요:
npx apifable@latest fetch팀과 공유할 수 있는 민감하지 않은 헤더의 경우, apifable.config.json에 spec.headers를 추가하세요:
{
"spec": {
"path": "openapi.yaml",
"url": "https://example.com/openapi.yaml",
"headers": {
"X-Api-Version": "2"
}
}
}원격 OpenAPI 사양을 다운로드하는 데 인증(비공개 API)이 필요한 경우, 비밀 헤더를 .apifable/auth.json에 저장하세요. 이 파일은 버전 관리 시스템에 커밋해서는 안 됩니다:
{
"headers": {
"Authorization": "Bearer YOUR_SECRET_TOKEN"
}
}apifable.config.json과 .apifable/auth.json 모두 헤더 값에서 ${ENV_VAR} 구문을 지원합니다.
{
"headers": {
"Authorization": "Bearer ${MY_API_KEY}"
}
}.apifable/auth.json 헤더 (동일한 이름의 키를 덮어씀)
apifable.config.json spec.headers
.mcp.json에 다음을 추가하세요:
{
"mcpServers": {
"apifable": {
"command": "npx",
"args": ["-y", "apifable@latest", "mcp"]
}
}
}Cursor나 Windsurf와 같은 다른 AI 에이전트의 경우, 동일한 방식으로 apifable을 MCP 서버로 구성할 수 있습니다.
API를 탐색하고 기능을 구축하는 데 사용할 수 있는 몇 가지 예시 프롬프트입니다.
List all APIsShow me APIs related to postsList APIs under the Post tagShow me the API details for post commentsShow me the API details for GET /posts/{id}/commentsShow me the API details for postCommentsImplement the post comments feature
Post page: src/pages/posts/[id].tsx
Related APIs:
- GET /posts/{id}/comments (list post comments)
- POST /posts/{id}/comments (create a post comment)[!TIP] 기능을 구축하기 위한 프롬프트를 작성할 때는 페이지 경로, 컴포넌트 위치, 관련 API, 따라야 할 패턴이나 예시 등 관련 컨텍스트를 포함하세요.
AI 에이전트가 apifable을 더 효과적으로 사용할 수 있도록 프로젝트의 AGENTS.md에 다음을 추가하세요:
## API Integration (apifable)
- Always use `get_endpoint` to verify the exact path, method, and parameters before writing integration code. Never assume.
- When presenting endpoint list data from apifable tools, display exactly these columns in order: `Method` (Uppercase), `Path`, `Summary`. Keep all values verbatim, including summary prefixes like `[ 32 - 001 ]`. Do not omit, rename, paraphrase, or add extra columns.
- When saving generated types, store them under `src/types/` and name files by domain (e.g., `src/types/auth.ts`, `src/types/user.ts`), not by OpenAPI tag names.위 내용은 권장되는 시작점입니다. 엔드포인트 목록 열과 타입 폴더 경로를 프로젝트에 맞게 자유롭게 조정하세요.
get_spec_infoAPI 제목, 버전, 설명, 서버, 그리고 엔드포인트 개수가 포함된 모든 태그를 반환합니다. 익숙하지 않은 사양의 형태를 파악하려면 여기서 시작하세요.
list_endpoints_by_tag입력:
tag (string): 필터링할 태그 이름
limit (number, 선택 사항): 반환할 최대 엔드포인트 수
offset (number, 선택 사항): 건너뛸 엔드포인트 수 (기본값: 0)
지정된 태그에 속하는 모든 엔드포인트를 반환합니다. 응답에는 페이지네이션을 위한 total, offset, hasMore 필드가 포함됩니다. 결과가 30개를 초과하고 limit이 지정되지 않은 경우 경고가 포함됩니다.
search_endpoints입력:
query (string): 검색할 키워드
tag (string, 선택 사항): 특정 태그로 검색 제한
limit (number, 선택 사항): 반환할 최대 결과 수 (기본값: 10)
operationId, 경로, 요약 및 설명을 대상으로 키워드 검색을 수행합니다. 결과는 관련성 순으로 정렬됩니다. 정확히 일치하는 항목이 없으면 자동으로 퍼지 검색으로 전환됩니다. 응답에는 matchType 필드("exact" 또는 "fuzzy")가 포함되며, 퍼지 결과에는 결과별 score 필드도 포함됩니다.
get_endpoint입력 (하나 선택):
method (string) + path (string): HTTP 메서드 및 엔드포인트 경로 (예: get + /users/{id})
operationId (string): 작업 ID (예: listUsers)
매개변수, requestBody, 응답을 포함한 전체 엔드포인트 객체를 반환하며, 지원되는 내부 컴포넌트 $ref는 인라인으로 해결됩니다.
search_schemas입력:
query (string): 검색할 키워드
limit (number, 선택 사항): 반환할 최대 결과 수 (기본값: 10)
스키마 이름 및 설명을 대상으로 키워드 검색을 수행합니다. 결과는 관련성 순으로 정렬됩니다. 정확히 일치하는 항목이 없으면 자동으로 퍼지 검색으로 전환됩니다. 응답에는 matchType 필드("exact" 또는 "fuzzy")가 포함되며, 퍼지 결과에는 결과별 score 필드도 포함됩니다. 결과가 비어 있는 경우 다음 단계를 위한 안내가 포함된 message 필드가 포함될 수 있습니다.
get_schema입력:
name (string): components/schemas의 스키마 이름
지원되는 내부 컴포넌트 $ref가 해결된 전체 스키마를 반환합니다.
get_types입력 (모드 하나 선택):
schemas (string[]): components/schemas의 스키마 이름 배열
method (string) + path (string): HTTP 메서드 및 엔드포인트 경로
operationId (string): 작업 ID (예: listUsers)
코드 텍스트로 독립적인 TypeScript 선언을 생성합니다. 엔드포인트 모드에서는 스키마 종속성을 수집하기 전에 지원되는 내부 컴포넌트 $ref를 따릅니다. 자동으로 전이적 종속성을 포함하며 import 문은 포함하지 않습니다.
모드 규칙:
호출당 정확히 하나의 모드만 사용: schemas, method + path, 또는 operationId
동일한 호출에서 모드를 혼합하지 마세요.
외부 $ref(예: 다른 파일이나 URL에 대한 참조)는 지원되지 않습니다.
OpenAPI 2.0(Swagger)은 지원되지 않습니다. OpenAPI 3.0 및 3.1 사양만 지원됩니다.
이 패키지가 도움이 되었다고 생각하신다면, 제 작업을 지원하기 위해 후원자가 되는 것을 고려해 주세요~ 후원해 주시면 제 주요 프로젝트에 귀하의 아바타가 표시됩니다.
@reapi/mcp-openapi — 초기 영감을 주었습니다.
Get full details of a specific endpoint including parameters, request body, responses, and security requirements. Supported internal component $refs are resolved inline. Provide either "method" + "path" or "operationId". Use get_types to get TypeScript type declarations for the endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Endpoint path (e.g. /users/{id}) | |
| method | No | HTTP method (e.g. get, post, put, delete) | |
| operationId | No | Operation ID to look up (e.g. listUsers) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that supported internal component $refs are resolved inline, which is a non-obvious behavioral trait, and lists the response contents. This goes beyond a simple 'gets details' and is transparent about processing.
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?
Three sentences with no redundancy: the first states purpose, the second adds a key behavioral detail, and the third gives usage and an alternative. Purpose is front-loaded, and 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?
For a simple get tool with no output schema and no required parameters, the description covers the return contents, the resolution behavior, and the input rules. It also points to a sibling for related needs. Nothing the agent needs to call it correctly is missing.
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 each parameter already described. The description adds value by specifying the mutual exclusivity (either method+path or operationId), which is not explicit in the schema. This relationship is critical for correct invocation, so the description compensates beyond the schema baseline.
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 'Get full details of a specific endpoint' and enumerates the exact contents (parameters, request body, responses, security requirements). It distinguishes this from sibling list/search tools by targeting a single endpoint, and also differentiates from get_types by specifying the type-declaration role.
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?
It explicitly instructs the caller to provide either 'method' + 'path' or 'operationId', which is a precise usage rule. It also names the alternative tool get_types for TypeScript declarations, giving clear routing criteria. This satisfies the when/alternative requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific schema from components/schemas by name. Supported internal component $refs are resolved inline. Use get_types to convert schemas to TypeScript type declarations.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Schema name (e.g. User, CreateOrderRequest) |
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 disclose a key behavioral trait: internal $refs are resolved inline. This goes beyond the schema. However, it doesn't mention error handling, permissions, or what happens when the schema is not found, which would add confidence for an agent.
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 compact sentences. The first states the core function and the inline-ref detail; the second gives a clear pointer to a related tool. No fluff, information density is high and 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?
For a simple one-parameter get operation with no output schema, the description covers the essential intent, the ref-resolution behavior, and a related alternative. It doesn't specify return shape or error cases, but those are less critical given the tool's simplicity. Slight gap in detail about failure modes prevents a 5.
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% for the only parameter ('name' is described with an example). The description's phrase 'by name' aligns with the param but adds no extra semantic detail beyond what the schema already provides. Baseline 3 is appropriate.
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 states a specific verb ('Get') and resource ('a specific schema from components/schemas by name'), and distinguishes itself from sibling tools like 'get_types' by mentioning conversion. It is clear which tool to use when you need a single named 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?
It explicitly tells the agent to use 'get_types' for TypeScript conversion, which clarifies a distinct use case. However, it does not explicitly contrast with 'search_schemas' (e.g., 'use search_schemas if you don't know the name'), so the 'when not to use' guidance is only implied. Still, the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get general information about the OpenAPI spec: title, version, description, servers, security schemes, and available tags with endpoint counts. Start here to understand an unfamiliar API. Then use list_endpoints_by_tag or search_endpoints to explore specific areas.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description implies a read-only operation without side effects; no annotations are provided, but the description adequately conveys the tool's behavior. Could potentially mention that it returns summary data, but overall transparent.
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 states purpose and contents, second gives usage guidance. Efficient, front-loaded, and 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?
For a parameterless tool with no output schema, the description fully explains what it returns (title, version, description, servers, security schemes, tags with counts) and how to use it.
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?
No parameters exist, so schema coverage is 100%. The description adds no parameter-specific info, but given no parameters, the baseline of 4 is appropriate.
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?
Clearly states it retrieves general information about the OpenAPI spec and lists specific items (title, version, etc.). Distinguishes from siblings by positioning it as the starting point and suggesting exploration tools like list_endpoints_by_tag 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?
Explicitly advises to 'Start here to understand an unfamiliar API' and then use list_endpoints_by_tag or search_endpoints for further exploration, providing clear when-to-use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate self-contained TypeScript type declarations for specified schemas or for all schemas used by a specific endpoint. Endpoint mode follows supported internal component $refs before collecting schema dependencies. Provide exactly one of: "schemas" (array of schema names), "method" + "path" (endpoint), or "operationId". Transitive dependencies are included automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Endpoint path for endpoint mode (e.g. /users/{id}) | |
| method | No | HTTP method for endpoint mode (e.g. get, post) | |
| schemas | No | Array of schema names from components/schemas (e.g. ["User", "Address"]) | |
| operationId | No | Operation ID to generate types for (e.g. listUsers) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that transitive dependencies are included automatically and that endpoint mode follows internal $refs, which is valuable. However, it doesn't mention side effects (though generation is likely read-only) or error behavior, leaving some transparency gaps.
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 dense paragraph that front-loads the purpose, then explains the modes, and ends with the dependency behavior. Every sentence contributes value; no filler or 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?
For a type-generation tool with no output schema, the description clearly states what it produces (self-contained TypeScript declarations) and how to invoke it. It lacks details about output format (e.g., string vs. file) and error cases, but these are minor given the simplicity of the 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?
The schema describes all four parameters fully (100% coverage), but the description adds critical semantics: the mutual exclusivity constraint and the meaning of each mode (schemas vs. method+path vs. operationId). This goes beyond the schema's individual parameter descriptions.
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 states a specific action (generate self-contained TypeScript type declarations) with a clear resource (schemas or endpoint-used schemas). It distinguishes from siblings like get_schema (which returns a single schema definition) and search_schemas (which searches), making the purpose unambiguous.
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?
It gives explicit input rules: 'Provide exactly one of: schemas, method+path, or operationId', and explains endpoint mode follows $refs. It doesn't explicitly contrast with alternatives, but the uniqueness of the tool (generating types vs. listing/searching) makes the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all endpoints belonging to a specific tag. Use get_spec_info first to see available tags. Supports pagination via limit and offset. Then use get_endpoint to inspect a specific endpoint in detail.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | The tag name to filter endpoints by | |
| limit | No | Maximum number of endpoints to return | |
| offset | No | Number of endpoints to skip (default: 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. 'List' implies a read-only operation and the suggestion to use get_endpoint for details implies response summaries, but auth requirements, response shape, and pagination edge cases are not disclosed. This 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-load the core purpose and follow with brief, useful workflow steps. The pagination mention is slightly redundant with the schema, but the overall structure is efficient with no fluff.
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 and no annotations, the description covers the core workflow and pagination, but leaves the return format and error behavior unstated. An agent could call it correctly, but would need to discover response details from a sample call rather than the description.
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%, so all three parameters are already documented. The description only restates limit/offset as pagination support, adding no new meaning beyond what the schema provides. Baseline 3 applies.
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 action ('List') and resource ('endpoints filtered by tag'). It is specific about the filter dimension, but does not explicitly contrast with sibling search_endpoints, so an agent must infer the distinction from the tag-based wording.
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?
Provides explicit workflow guidance: call get_spec_info first to discover valid tags and use get_endpoint afterward for detail. It gives a clear context for when this tool fits, but does not state when to prefer search_endpoints or when not to use this tool, so exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search endpoints by keyword across operationId, path, summary, and description. Results are ranked by relevance. If no exact matches are found, automatically falls back to fuzzy search. The response includes a matchType field ("exact" or "fuzzy"); fuzzy results also include a score field per result. After finding the target endpoint, use get_endpoint for full details or get_types for TypeScript types.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Optional tag to filter results | |
| limit | No | Maximum number of results (default: 10) | |
| query | Yes | Search keyword |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the fallback behavior, the matchType field, and the score field for fuzzy results. It doesn't mention pagination or error behavior, but for a read-only search tool, the described behavior is transparent enough. The absence of annotations is compensated by this explicit behavioral detail.
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 few sentences, front-loaded with the primary action and scope. It covers the fallback, output fields, and follow-up tools without unnecessary filler. It is concise and well-structured, earning a score above average.
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 the lack of an output schema, the description provides essential return information (matchType, score) and suggests next steps. It covers the core search behavior and result format. While it doesn't address edge cases like no results or error conditions, for a search tool with simple parameters, the description is sufficiently complete for an agent to use it correctly.
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 input schema already documents all three parameters (tag, limit, query) with descriptions, so schema coverage is 100%. The tool description adds context about result ranking and matchType/score fields, but these are about output, not parameter semantics. It doesn't elaborate on parameter usage beyond what the schema provides, so a baseline of 3 is appropriate.
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 states a specific verb (search) and resource (endpoints), and clarifies the scope (operationId, path, summary, description). It also mentions ranking by relevance and the fallback to fuzzy search, which distinguishes it from sibling tools like list_endpoints_by_tag and get_endpoint. The purpose is unambiguous and clearly differentiates from alternatives.
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 provides explicit guidance on when to use this tool and what to do next: it mentions the automatic fallback to fuzzy search and directs the user to get_endpoint or get_types after finding the target. It doesn't explicitly state when not to use it, but the follow-up instructions and the optional tag filter give enough context for an agent to decide when this is the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search schemas by keyword across schema name and description. Results are ranked by relevance. If no exact matches are found, automatically falls back to fuzzy search. Empty results may include a guidance message suggesting next steps. Use get_schema to inspect a specific schema in detail.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (default: 10) | |
| query | Yes | Search keyword |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers: results are relevance-ranked, there is an automatic fuzzy-search fallback when no exact matches exist, and empty results may include a guidance message suggesting next steps. These are non-obvious behaviors an agent needs to interpret results correctly. Minor gaps are the lack of an explicit read-only confirmation and any pagination/result-cap behavior beyond what the schema's limit parameter already states.
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?
Five sentences, each earning its place: core purpose, ranking behavior, fuzzy fallback, empty-result guidance, and sibling routing. The description is front-loaded with the primary purpose and contains zero redundancy or filler. It is compact while carrying all essential 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?
For a simple 2-parameter search tool with no output schema and no annotations, the description covers search scope, relevance ranking, fuzzy fallback, empty-result behavior, and the next-step route to get_schema. The one gap is that no output schema exists and the description does not sketch the result shape, but for a keyword search tool this is a minor omission given the tool's simplicity.
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%, so both query and limit are already documented in the schema with meaningful descriptions. The tool description adds contextual enrichment (query matches against name and description, fuzzy fallback behavior) but no parameter-level syntax or format detail beyond what the schema provides. The baseline 3 applies because the schema does the heavy lifting.
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 opens with a specific verb+resource+scope: 'Search schemas by keyword across schema name and description.' It clearly distinguishes from sibling get_schema by naming it as the inspection path, and the scope wording ('schemas... across schema name and description') implicitly differentiates from search_endpoints. An agent can tell what this tool does without opening the 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?
The description gives an explicit routing instruction: 'Use get_schema to inspect a specific schema in detail,' which tells the agent when this search tool is the wrong choice. The fallback and relevance-ranking notes clarify the trustworthiness of results. However, it never explicitly names search_endpoints as the alternative for endpoint search, leaving that sibling distinction implicit rather than stated.
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.
v1.2.0get_endpoint1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"get_schema1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"get_types1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"list_endpoints_by_tag1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"search_endpoints1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"search_schemas1 field changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"v1.1.1get_endpointget_schemaget_spec_infoget_typeslist_endpoints_by_tagsearch_endpointssearch_schemasScored across 7 tools
Each tool targets a distinct action: spec overview, endpoint search/list/detail, schema search/detail, and TypeScript generation. No two tools overlap in purpose, and cross-references between them make selection clear.
All tools use a consistent lowercase snake_case verb_noun pattern: get_, search_, and list_. Even the longer list_endpoints_by_tag follows the same predictable convention.
Seven tools is well-scoped for an OpenAPI exploration and type-generation server. Each tool fills a distinct role without redundancy or bloat.
The surface covers the core exploration workflow well: discover spec info, find endpoints/schemas, inspect details, and generate TypeScript types. Minor gaps exist such as no way to list all schemas or all endpoints globally, but these are workable through tags and search.
MCP server for AI access to Swagger by SmartBear.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.