Real API implementation of MCP server for Guepard Platform - provides tools for database deployments, authentication, branches, snapshots, compute resources, performance profiles, and monitoring
The server exposes 21 tools with basic schema definitions and descriptions. However, quality is inconsistent across the toolset. Strengths: all tools have descriptions and input schemas visible in code; tool names follow verb_noun convention (start_login, list_branches, etc.); authentication-related tools are well-structured. Weaknesses: output schemas are not documented anywhere in the source code provided; many parameter descriptions are minimal (under 72 chars baseline) and lack constraint details (ranges, formats, dependencies); no error handling guidance visible in tool implementations; no tool annotations (readOnlyHint/destructiveHint/idempotentHint) despite clear distinction between read and write operations; security-critical auth tools accept sensitive parameters (email, password) without warnings about secret injection; no pagination details documented for list tools; no confirmation patterns for destructive operations. Schema completeness varies: auth tools have good structures, but compute/deployment tools lack explicit output schema documentation. The perToolScores reveal a median per-tool score of ~54, consistent with 'poor but functional' implementations.
Tools (21)
checkout_branchwriteauthsource verified67/100
Checkout to a specific branch with snapshot
checkout_snapshotwriteauthsource verified63/100
Get a deployment, randomly select one of its branches, randomly select one of its snapshots, then checkout to that snapshot
Output schemas are completely undocumented. No tool in the server declares what fields it returns, their types, or structure. This prevents LLMs from planning downstream tool calls and extracting correct data.
Security-critical auth tools (login_supabase, resume_login) accept plaintext email and password as parameters without any warning about secret injection. Credentials must never appear as tool parameters, use server-side secret injection via environment variables.
login_supabase
Recommendations
Add explicit output schema documentation to all 21 tools. Each tool definition should include an outputSchema field with typed fields and descriptions. Example: { name: 'list_branches', outputSchema: { type: 'object', properties: { branches: { type: 'array', items: { type: 'object', properties: { branch_id: { type: 'string' }, label_name: { type: 'string' } } } }, total_count: { type: 'integer' } } } }
Refactor authentication tools to NOT accept credentials as parameters. Instead: (1) require authentication token via Authorization header or environment variable, (2) if plaintext auth is necessary, use a server-side 'initialize authentication' phase that securely exchanges credentials for a session, (3) all subsequent tool calls reference the session. This removes credentials from tool parameters and agent logs.
Add tool annotations to all write/destructive tools. Modify the tool registration in src/guepard_mcp/utils/base.py to include: destructiveHint (for end_login, stop_compute, checkout_snapshot), idempotentHint (for create_deployment if it supports idempotency keys). This enables MCP clients to warn before executing irreversible operations.
Enhance pagination for all list_* tools: Add 'limit' (default 20, max 100) and 'offset' or 'cursor' parameters. Document in tool description: 'Returns max 20 results. Use offset parameter to fetch additional pages.' Return a 'total_count' field so agents know if more results exist.
Expand parameter descriptions to 50-100 characters, including constraints and when to use. Example: Instead of 'Deployment ID', write: 'UUID of the deployment to query. Required for all deployment operations. Pass the deployment ID returned from create_deployment or list_deployments.'
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) present despite clear semantic distinction. Tools like stop_compute, delete_deployment (implied), and create_branch_from_snapshot should explicitly declare their side effects.
List tools (list_branches, list_deployments, list_f2_deployments) lack pagination parameters (limit, offset, cursor) and do not document max result counts.
Parameter descriptions are consistently minimal. Examples: 'Deployment ID' (15 chars), 'Branch ID' (9 chars), 'Snapshot ID' (11 chars). Baseline is 72 chars average. These descriptions lack context about format, constraints, or when to use alternatives (e.g., when to pass deployment name vs ID).
No error handling guidance in tool implementations. The provided code shows format_error_response() calls but no detail on what errors are recoverable, which require user action, or what the LLM should do next.
Destructive operations (stop_compute, end_login, checkout_branch with side effects) have no confirmation or dry-run option. Agents can inadvertently stop production workloads.
Several tools have trivial or absent descriptions: list_f2_deployments ('Get all F2 deployments', 31 chars), list_image_providers ('Get all available database image providers', 44 chars). These fail to answer WHEN to use the tool or what it returns.
Parameter dependencies are undocumented. For example, create_deployment has optional parameters (deployment_type, database_version) with unclear interaction: 'deployment_type auto-selects based on context' is vague and will confuse agents.
Tool response implementation truncates tokens (e.g., verify_session returns access_token[:20] + '...'). While this prevents leaking secrets to logs, it breaks the tool's utility, agents cannot use truncated tokens for subsequent API calls.
verify_session
Add error handling guidance to tool descriptions. Example: 'If the deployment is not found, call list_deployments() to discover available IDs. If the deployment is in a stopped state, call start_compute() first.'
Implement a confirmation pattern for destructive operations. Add optional parameters like 'confirm: true' or a 'dry_run: true' mode. Document: 'This operation stops the deployment permanently. Pass confirm=true to proceed, or use dry_run=true to preview the effect.'
Document parameter dependencies explicitly. For create_deployment, clarify: 'deployment_type determines valid database_provider options: REPOSITORY accepts PostgreSQL|mysql|mongodb; F2 only accepts the parent deployment's provider. If both deployment_parent and deployment_type='REPOSITORY' are provided, deployment_type takes precedence.'
Return complete tokens in responses, not truncated. If token leakage to logs is a concern, implement server-side token masking or use a separate secure_token exchange endpoint. Agents MUST be able to use returned tokens for follow-up API calls.
Add input validation with actionable error messages. Instead of returning raw API errors, validate enums, required fields, and constraints in the tool handler. Example error: 'Invalid status filter: got "archived", must be one of: active, pending, failed, terminated. Call list_deployments() without a status filter to see all options.'