docs: add MCP Security Gateway specification v1.0

[Imran Siddique (imran-siddique)]

Summary

Adds formal specification for the MCP Security Gateway with conformance tests.

Specification (docs/specs/MCP-SECURITY-GATEWAY-1.0.md)

22-section specification covering:

• Gateway architecture with tool call/response interception pipeline
• Security scanner detecting 6 threat types (tool poisoning, rug pull, cross-server attack, confused deputy, hidden instruction, description injection)
• Response scanning with 3 policies (block, sanitize, log)
• HMAC message signing with replay protection (5-minute window, 10K nonce cache)
• Session authentication (1-hour TTL, 10 max concurrent, bootstrap sessions)
• Sliding window rate limiting (100 calls per 5-minute window)
• Auth method enforcement (oauth2, mTLS, API key, bearer, none)
• CVE feed integration via OSV API with 1-hour cache
• Trust-gated MCP server/client with per-tool capability requirements
• Agent SRE MCP tool registry for SLO/cost/rollout operations
• Schema drift detection with 8 drift types and baseline comparison
• Fail-closed failure semantics throughout

Conformance Tests (agent-os/tests/test_spec_mcp_gateway_conformance.py)

127 tests across 11 test classes, all passing:

• TestGatewayInterception, TestResponseScanning, TestSecurityScanner
• TestMessageSigning, TestSessionAuth, TestSlidingRateLimiter
• TestAuthEnforcement, TestCveFeed, TestMetrics
• TestDriftDetection, TestFailureSemantics

Notes

• Sixth spec in the series (Policy Engine, Identity/Trust, Hypervisor, Mesh Trust, SRE, MCP Gateway)

[github-actions]

🤖 AI Agent: breaking-change-detector — View details

No breaking changes detected.

[github-actions]

🤖 AI Agent: code-reviewer — Action Items:

TL;DR: 0 blockers, 1 warning. Specification and tests are comprehensive but require minor follow-up.

#	Sev	Issue	Where
1	Warn	Test coverage for edge cases could improve	test_spec_mcp_gateway_conformance.py

Action Items:

• None.

Warnings:

#	Issue	Where	Follow-up
1	Test coverage for edge cases could improve	test_spec_mcp_gateway_conformance.py	Fine as follow-up PR

No critical issues found.

[github-actions]

🤖 AI Agent: security-scanner — View details

No security issues found.

[github-actions]

🤖 AI Agent: test-generator — `agent-os/mcp_gateway.py`

agent-os/mcp_gateway.py

• test_intercept_tool_call_error_handling -- Validate behavior when intercept_tool_call receives invalid or malformed input.
• test_sensitive_tool_callback_exceptions -- Ensure gateway handles exceptions raised by the approval callback gracefully.
• test_audit_log_overflow_handling -- Verify audit log behavior when the log size exceeds a predefined limit.

agent-os/mcp_response_scanner.py

• test_scan_response_invalid_tool_name -- Test scanner behavior when provided with an invalid or missing tool name.
• test_sanitize_response_large_input -- Validate performance and correctness when sanitizing very large response content.
• test_scan_response_unexpected_data_types -- Ensure scanner handles non-string response content gracefully.

agent-os/mcp_security.py

• test_scan_result_multiple_threats -- Verify ScanResult correctly aggregates multiple threats detected in a single scan.
• test_tool_fingerprint_mismatch -- Test behavior when tool fingerprint validation fails.
• test_security_scanner_invalid_input -- Ensure security scanner handles invalid or unexpected input gracefully.

agent-os/mcp_message_signer.py

• test_message_signing_invalid_key -- Validate behavior when signing messages with an invalid or corrupted key.
• test_replay_protection_expired_nonce -- Ensure expired nonces are correctly rejected during verification.
• test_signed_envelope_tampering -- Test detection of tampering in signed envelopes.

agent-os/mcp_session_auth.py

• test_session_auth_invalid_ttl -- Validate behavior when session TTL is set to an invalid value.
• test_concurrent_session_limit_exceeded -- Ensure correct handling when the maximum concurrent session limit is exceeded.
• test_session_auth_expired_session -- Verify behavior when attempting to authenticate with an expired session.

agent-os/mcp_sliding_rate_limiter.py

• test_rate_limiter_negative_window -- Ensure rate limiter handles invalid negative window values gracefully.
• test_rate_limiter_high_volume -- Validate rate limiter performance under high request volume.
• test_rate_limiter_reset -- Test behavior when resetting rate limiter state.

agent-os/mcp_auth_enforcement.py

• test_auth_policy_invalid_method -- Verify behavior when an invalid authentication method is configured.
• test_auth_check_failure_handling -- Ensure proper handling of failed authentication checks.
• test_auth_policy_update -- Test dynamic updates to authentication policies.

agent-os/mcp_cve_feed.py

• test_cve_feed_invalid_package -- Validate behavior when querying CVE feed with invalid package data.
• test_cve_feed_cache_eviction -- Ensure cache eviction works correctly after the specified duration.
• test_cve_feed_api_error_handling -- Test behavior when the OSV API returns errors or unexpected responses.

agent-os/_mcp_metrics.py

• test_metrics_recorder_invalid_metric -- Validate behavior when recording an invalid or unsupported metric.
• test_metrics_recorder_high_frequency -- Ensure metrics recorder handles high-frequency updates without performance degradation.
• test_no_op_metrics_behavior -- Verify behavior when using NoOpMCPMetrics in place of a real metrics recorder.

agent-sre/integrations/mcp.py

• test_drift_detector_invalid_schema -- Test behavior when drift detection encounters an invalid schema.
• test_drift_report_multiple_alerts -- Verify DriftReport correctly aggregates multiple drift alerts.
• test_drift_detector_unexpected_drift_type -- Ensure drift detector handles unexpected drift types gracefully.

[github-actions]

PR Review Summary

Check	Status	Details
🔍 Code Review	❌ Failed	Issues detected
🛡️ Security Scan	✅ Passed	No issues found
🔄 Breaking Changes	✅ Passed	No issues found
📝 Docs Sync	⏳ Pending	Awaiting results
🧪 Test Coverage	✅ Completed	Analysis complete

Verdict: ❌ Changes needed