dynamic-mcp provides HTTP-exposed tools with structured input schemas and basic descriptions, but falls short of production-grade quality. Tool names follow verb conventions (initialize, exec, run_js, stop, list), but descriptions are inconsistent in depth. Several parameters lack descriptions entirely (e.g., adminToken across all sandbox tools, image in initialize), forcing LLMs to infer intent. Schemas are present and use Zod validation internally, but output structures are not formally documented in the tool definitions. Error handling exists (guard/audit) but doesn't surface recovery guidance to agents. The sandbox tools mix authentication concerns (adminToken as a parameter) with functional parameters, violating secret-injection patterns. Overall, this is a functional but incomplete implementation, comparable to a C+ grade.
Tools (9)
dev.echoread onlysource verified85/100
Echo user input and return deterministic structured output
fixture.pingread onlysource verified57/100
Simple fixture tool used by upstream attach integration tests
sandbox.execirreversibleauthsource verified65/100
Run one or more shell commands in an active sandbox session
sandbox.initializewriteauthsource verified60/100
Create a reusable container session for iterative commands and scripts
adminToken exposed as tool parameter instead of server-side secret injection. Credentials in parameters are logged in agent traces and prompt history, creating a security leak.
Parameters lack descriptions across sandbox tools. 'adminToken' appears in 5 tools with no explanation of format or purpose. 'image' in sandbox.initialize has no description. LLMs cannot determine what values are valid without explicit guidance.
No output schemas documented in tool definitions. Responses return content + structuredContent, but the LLM has no formal specification of what fields to expect (e.g., what does 'structuredContent' contain in sandbox.initialize?). This forces agents to infer structure from untyped responses.
Recommendations
Move adminToken from parameter to server-side environment variable / vault injection. Agents should authenticate via server credentials, not pass tokens in parameters. Update sandbox tool schemas to remove adminToken parameter entirely.
Add parameter descriptions for all sandbox tools. Document adminToken format (if client-provided) or state 'authenticated via server config'. Describe image parameter (allowed images list, format). Describe timeoutMs range and default. Example: 'timeoutMs: request timeout in milliseconds, range 1000 - 120000, defaults to server config. Must be smaller than session lifetime.'
Formalize output schemas in tool definitions. Each tool should specify what structuredContent contains (e.g., sandbox.initialize returns {sessionId: string, image: string, timeoutMs: number}). This makes LLM response parsing reliable.
Enhance error handling to guide agent recovery. Instead of raw validation errors, return: 'Invalid image: got "python:2.7". Allowed images: node:lts-slim, python:3.11, ubuntu:24.04. Available images: [list]. Or call sandbox.initialize with no image to use default.'
Add optional confirmation/dry-run pattern for irreversible tools. sandbox.exec and sandbox.run_js could accept a 'dryRun: boolean' parameter. When true, return what would execute without executing. This reduces catastrophic mistakes.
Expand tool descriptions to include prerequisites and decision logic. Example for sandbox.exec: 'Execute shell commands in a running sandbox session. Requires an active session created via sandbox.initialize. Commands run in isolation with no network. Output captured up to 10MB. Use for debugging, building, or testing. Errors are non-fatal per command; check result for failures.'
Error responses do not guide recovery. Errors from guard/audit layers likely return stack traces or generic messages without telling the agent what to do next (retry, fix input, call a discovery tool, etc.).
Destructive tools (sandbox.exec, sandbox.run_js, sandbox.stop) lack confirmation or dry-run patterns. Agents can delete containers or run arbitrary code without a confirmation step, risking irreversible mistakes.
Tool descriptions for sandbox operations are generic (e.g., 'Create a reusable container session') and do not explain when to use them, what permissions are required, or what constraints apply (e.g., max 120s timeout, max 64 dependencies). LLMs cannot optimize tool selection without this context.
No validation error messages. If an agent passes an invalid image, invalid timeout, or too many dependencies, the tool should return a clear, actionable error with the constraint violated and valid options. Current code likely returns raw validation errors from Zod without formatting for LLM recovery.
Permission model is binary (adminToken check) with no scope declaration. Tools do not advertise what permissions they require, making it impossible for clients to configure least-privilege agents or understand audit implications.
Implement structured error classification: (a) retryable errors (network timeout, transient Docker failure) → guide agent to retry; (b) user-fixable errors (invalid image, bad syntax) → show constraint violation and valid options; (c) fatal/permission errors → explain why and suggest alternatives.
Add scope declarations to sandbox tools. Each should state required permissions, e.g., 'Requires: sandbox:admin' or 'Requires: sandbox:execute'. This enables clients to configure least-privilege agent tokens and understand audit compliance.
Document rate limits and resource constraints explicitly. The tool description should mention: max 256 concurrent sessions, 120s timeout cap, 10MB output buffer, max 64 npm dependencies. This helps agents avoid resource exhaustion errors.
Consider adding a batch variant for common multi-step patterns. E.g., sandbox.runScript(sessionId, script, dependencies, timeout) to combine npm install + run in one call, reducing round-trips and tokens.