{"slug": "mcp-probe-v1-4-0-contract-assertions-for-production-mcp-servers", "title": "mcp-probe v1.4.0: Contract assertions for production MCP servers", "summary": "The article announces the release of mcp-probe v1.4.0, a tool that adds contract assertions for production MCP servers. It explains that basic startup and schema checks are insufficient for production environments, as servers can pass these checks but still fail due to broken auth, permissions, or data boundaries. The new version allows teams to define expected outcomes for tool calls—such as status, required fields, error codes, and content checks—enabling CI pipelines to validate the actual contracts that AI agents depend on.", "body_md": "MCP servers are starting to look like infrastructure.\nThat means the old readiness question is no longer enough:\nDoes the process start?\nEven this is not enough:\nDoes\ntools/list\nreturn a clean schema?\nA server can pass both checks and still fail every real agent loop because auth handoff, scopes, downstream permissions, environment setup, or data boundaries are broken.\nSo I shipped mcp-probe v1.4.0 with contract assertions for production MCP servers.\nGitHub: https://github.com/k08200/mcp-probe\nnpm: https://www.npmjs.com/package/@k08200/mcp-probe\nA typical MCP smoke test looks like this:\ninitialize\ntools/list\nThat catches broken startup and malformed tools.\nBut it misses the failures that matter in production:\n401\nIn other words: the server starts, but the contract is broken.\nmcp-probe already supported sidecar inputs via .mcp-probe.json\nso teams could run real tools/call\nchecks instead of relying on schema-minimum dummy inputs.\nv1.4.0 extends that sidecar with assertions.\nExample for a database-backed MCP server:\n{\n\"tools\": {\n\"execute_sql\": {\n\"input\": {\n\"project_id\": \"YOUR_PROJECT_ID\",\n\"query\": \"select 1 as health_check\"\n},\n\"expect\": {\n\"status\": \"pass\",\n\"requiredFields\": [\"rowCount\", \"limit\", \"source\", \"freshness\"],\n\"maxRows\": 100\n}\n},\n\"execute_sql_write_denied\": {\n\"input\": {\n\"project_id\": \"YOUR_PROJECT_ID\",\n\"query\": \"delete from users where id = 1\"\n},\n\"expect\": {\n\"status\": \"fail\",\n\"errorCode\": \"WRITE_NOT_ALLOWED\",\n\"notContains\": [\"DATABASE_URL\", \"password\", \"stack\"]\n}\n}\n}\n}\nNow CI can validate the contract an agent actually depends on.\nexpect.status\nDeclare whether a call should pass, fail, or warn.\nThis is important for negative probes. A write attempt against a read-only DB role should fail. In that case, failure is success.\n{\n\"expect\": {\n\"status\": \"fail\"\n}\n}\nexpect.requiredFields\nValidate that result metadata exists.\nFor database tools, an agent often needs more than rows. It needs context:\nrowCount\nlimit\nsource\nfreshness\n{\n\"expect\": {\n\"requiredFields\": [\"rowCount\", \"limit\", \"source\", \"freshness\"]\n}\n}\nexpect.maxRows\nCatch broad exports or missing limits.\n{\n\"expect\": {\n\"maxRows\": 100\n}\n}\nmcp-probe looks for common result shapes such as rowCount\n, rowsReturned\n, rows\n, data\n, items\n, and records\n.\nexpect.errorCode\nRequire stable structured error codes.\n{\n\"expect\": {\n\"status\": \"fail\",\n\"errorCode\": \"WRITE_NOT_ALLOWED\"\n}\n}\nThis matters because agents can only recover if errors are predictable.\nexpect.contains\nand expect.notContains\nCheck for expected output and leaked internals.\n{\n\"expect\": {\n\"notContains\": [\"DATABASE_URL\", \"password\", \"stack\"]\n}\n}\nThis catches errors that expose raw internals.\nexpect.not_error_code\nTreat known auth/permission status codes as warnings instead of hard failures.\n{\n\"expect\": {\n\"not_error_code\": [401, 403]\n}\n}\nThis keeps OAuth handoff failures visible without confusing them with transport or runtime crashes.\nWhen assertions pass:\nTool Call Dry-run\n✓ db_query [sidecar] 1ms\n✓ status: Tool status matched expected pass\n✓ requiredFields.rowCount: Found required field \"rowCount\"\n✓ requiredFields.limit: Found required field \"limit\"\n✓ requiredFields.source: Found required field \"source\"\n✓ requiredFields.freshness: Found required field \"freshness\"\n✓ maxRows: Row count 1 is within maxRows 100\n✓ db_write [sidecar] 0ms\n✓ status: Tool status matched expected fail\n✓ errorCode: Found expected error code WRITE_NOT_ALLOWED\n✓ notContains.DATABASE_URL: Output does not contain \"DATABASE_URL\"\n✓ notContains.password: Output does not contain \"password\"\n✓ notContains.stack: Output does not contain \"stack\"\nIf a contract assertion fails, mcp-probe reports:\nCONTRACT_ASSERTION_FAILED\nand includes per-assertion details in terminal output, JSON output, and GitHub Actions summaries.\nnpx @k08200/mcp-probe@latest init \\\n--target @your-org/your-mcp-server \\\n--discover \\\n--github-actions\nThen edit .mcp-probe.json\nwith real read-only probes and run:\nnpx @k08200/mcp-probe@latest --config mcp-probe.config.json --github-summary\nMCP CI should test the contract an agent will actually depend on, not just whether the server process starts.\nFor database-backed MCP servers, that means validating things like:\nmcp-probe should not know every server's semantics. But it can give teams a small, declarative way to encode the production contract their agents rely on.\nThat is the goal of v1.4.0.\nRelease: https://github.com/k08200/mcp-probe/releases/tag/v1.4.0\nnpm: https://www.npmjs.com/package/@k08200/mcp-probe", "url": "https://wpnews.pro/news/mcp-probe-v1-4-0-contract-assertions-for-production-mcp-servers", "canonical_source": "https://dev.to/k08200/mcp-probe-v140-contract-assertions-for-production-mcp-servers-4ig9", "published_at": "2026-05-23 15:53:52+00:00", "updated_at": "2026-05-23 16:34:25.651210+00:00", "lang": "en", "topics": ["developer-tools", "open-source", "artificial-intelligence", "data"], "entities": ["mcp-probe", "GitHub", "npm"], "alternates": {"html": "https://wpnews.pro/news/mcp-probe-v1-4-0-contract-assertions-for-production-mcp-servers", "markdown": "https://wpnews.pro/news/mcp-probe-v1-4-0-contract-assertions-for-production-mcp-servers.md", "text": "https://wpnews.pro/news/mcp-probe-v1-4-0-contract-assertions-for-production-mcp-servers.txt", "jsonld": "https://wpnews.pro/news/mcp-probe-v1-4-0-contract-assertions-for-production-mcp-servers.jsonld"}}