A universal MCP server that connects any REST API (via OpenAPI spec) to AI assistants, with GraphQL-style field selection and automatic schema inference.
The server has 5 tools with reasonable names and partial schema documentation. Tool naming follows verb-first convention (list_, inspect_, query_, mutate_, auth) which is good. However, descriptions vary in quality and depth. Schemas are present but incomplete, many parameters lack detailed type constraints and examples. Parameter descriptions exist but are often generic. Error handling and recovery guidance are minimal. Output schemas are not explicitly documented in the visible code. The implementation shows decent structure but falls short of production-grade agent-tool standards.
Tools (5)
authwrite50/100
Initiate OAuth 2.0 authorization flow or manually set authentication token
inspect_apiread only50/100
Inspect detailed information about a specific API endpoint including parameters, request body schema, and response format
list_apiread only50/100
List available API endpoints with pagination and filtering
mutate_apiwriteauth50/100
Execute a POST, PUT, PATCH, or DELETE request to an API endpoint with optional JSON Patch support for targeted updates
query_apiread onlyauth50/100
Execute a GET request to an API endpoint with optional GraphQL-style field selection
Output schemas are not documented. Tools return unspecified result structures, forcing LLMs to infer what fields exist and their types. Without documented output schemas, agents cannot plan downstream calls or extract required fields reliably.
query_api and mutate_api have ambiguous, overloaded parameter sets. 'method' is required but description does not clarify which HTTP methods are valid, nor does it warn about idempotency implications. 'params' object lacks structure, is it query params, path params, or both? LLMs will guess wrong.
auth tool has vague action parameter. Description says 'Either oauth or set_token' but does not explain OAuth flow mechanics, callback handling, or token expiration. 'token' parameter is required only when action='set_token', but schema does not enforce this conditional dependency.
auth
Recommendations
Document output schemas for all 5 tools. Use JSON Schema notation to specify return value structure, field types, and required fields. Example for list_api: { type: 'object', properties: { endpoints: { type: 'array', items: { type: 'object', properties: { method: { type: 'string' }, path: { type: 'string' }, summary: { type: 'string' } } } }, total_count: { type: 'integer' }, offset: { type: 'integer' } } }.
Separate query_api and mutate_api into method-specific tools: get_api, post_api, put_api, patch_api, delete_api. This eliminates the 'method' parameter and makes each tool's intent unambiguous. Each tool name and description will self-document what HTTP verb is used.
Add enum constraints to method parameters in current tools. Instead of free-form 'method' string, declare: { type: 'string', enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'] }. This prevents hallucinated HTTP verbs.
Clarify auth tool's 'action' parameter with an enum: { type: 'string', enum: ['oauth', 'set_token'], description: 'Use oauth to initiate OAuth 2.0 flow (returns authorization URL for user to visit). Use set_token to manually inject a Bearer token. After OAuth, the agent will receive a token via callback.' }. Document callback mechanism and token storage.
Document conditional parameter logic for auth. Add description: 'token: Required when action=set_token. Ignored when action=oauth.' Use JSON Schema 'dependentRequired' if available in the SDK.
Add error handling section to each tool description. Example for query_api: 'Errors: HTTP 404 (endpoint not found), 401 (auth required), 500 (server error). If you receive 404, try inspect_api to verify the endpoint path. If 401, call auth with set_token first.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
No error handling guidance. Tools do not document what errors can occur (network timeout, auth failure, invalid path, rate limit, malformed body) or how LLMs should respond. A raw HTTP 500 or 'Connection refused' gives agents nothing actionable.
query_api 'select' parameter description references GraphQL-style field selection but does not document syntax, valid characters, nesting depth, or error messages if syntax is invalid. LLMs will try random formats and fail silently.
mutate_api 'bodyFile' parameter accepts absolute file paths. No validation, path traversal guards, or symlink checks documented. If the server runs with elevated privileges, this is a security risk. LLMs could be tricked into reading/writing arbitrary files.
list_api returns paginated results but response structure is not documented. What fields does a single API endpoint entry contain? Is there a 'total_count' field? A 'next_cursor'? Without documented output, agents cannot build multi-page loops.
inspect_api description says 'including parameters, request body schema, and response format' but does not specify the output structure. What JSON shape is returned? What fields describe a parameter? This forces LLMs to guess and fail on unexpected formats.
inspect_api
For query_api 'select' parameter, document the exact syntax and provide examples: 'GraphQL-style field selection (comma-separated, dot-notation for nested fields). Example: user.name,user.email,posts.id,posts.title. Invalid syntax returns a 400 error listing allowed fields.'
Add input validation and documentation for mutate_api 'bodyFile'. State: 'Absolute path to a local JSON file. Path must be under the server's working directory, no symlinks or ../traversal allowed. File must be readable and valid JSON.' Implement path validation inside the tool handler.
For list_api, document pagination in the response. Example output description: '{ endpoints: [{ method, path, operationId, summary }], total_count: integer, offset: integer, limit: integer }. If total_count > offset + limit, more results exist, use list_api with offset = offset + limit to fetch the next page.'
Add rate limiting guidance to all tools. Document: 'Rate limit: X requests per minute. If you receive HTTP 429, wait before retrying. Backoff strategy: wait 1s, then 2s, then 5s.'
Add tool annotations where applicable. Mark query_api and list_api with readOnlyHint: true. Mark mutate_api with destructiveHint: true (if DELETE is possible). Mark auth with destructiveHint: true (tokens can be revoked). These hints help agents reason about side effects.