SyslogSolution/prose-contracts
7
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add MCP server URL validation to hermes-config-template contract #114

Merged
mumuni-bot merged 4 commits from fm/hermes-config-mcp-url-validation into master 2026-09-17 13:22:32 +00:00
Conversation 0 Commits 4 Files Changed 2
+99 -9
abiba-bot commented 2026-09-17 12:47:40 +00:00
Owner
Copy Link
Copy Source

Summary

Adds MCP server URL validation to the hermes-config-template contract, addressing the 2026-08-07 keyless-MCP incident.

Changes

  1. Add litellm MCP server entry to mcp_servers section
  2. Enhance Rule 15 with MCP endpoint and header validation
  3. Add MCP Server Configuration section
  4. Add MCP server checks to audit-hermes-config.py

Verification

Verified MCP access with real agent keys via MCP initialize handshake (not just /v1 endpoint).

Acceptance Criteria

  • ✅ hermes-config-template.prose.md has both ra-h-os AND litellm MCP server entries
  • ✅ Rule 15 is present and clear
  • ✅ MCP access verified with real keys
  • ✅ PR created
## Summary Adds MCP server URL validation to the hermes-config-template contract, addressing the 2026-08-07 keyless-MCP incident. ## Changes 1. Add litellm MCP server entry to mcp_servers section 2. Enhance Rule 15 with MCP endpoint and header validation 3. Add MCP Server Configuration section 4. Add MCP server checks to audit-hermes-config.py ## Verification Verified MCP access with real agent keys via MCP initialize handshake (not just /v1 endpoint). ## Acceptance Criteria - ✅ hermes-config-template.prose.md has both ra-h-os AND litellm MCP server entries - ✅ Rule 15 is present and clear - ✅ MCP access verified with real keys - ✅ PR created
abiba-bot added 4 commits 2026-09-17 12:47:40 +00:00
feat: add litellm MCP server entry and enhance Rule 15 validation d2bca5405a 
- Added litellm MCP server entry to mcp_servers section with correct URL
  (https://litellm.sysloggh.net/mcp) and header format
- Updated Rule 15 to be more specific about endpoint validation and
  header requirements (REAL keys, not env-var references)
- Added MCP Server Configuration section with implementation details
- Documented the 2026-08-07 Tanko incident where ra-h-os was pointing
  to litellm endpoint with env header causing 401 floods
- Updated frontmatter to reflect the changes

Fixes: #keyless-mcp-incident-20260807
Refs: Rule 15 (MCP Endpoint and Header Validation)
docs: add MCP verification details and Accept header note 077972fa2b 
- Documented MCP endpoint verification (2026-08-07): tested with real key,
  confirmed initialize handshake works and virtual keys have MCP access
- Added note about Accept header requirement (handled by MCP client library)
- Clarified that the Accept header is NOT part of the config template
fix: address review findings for MCP URL validation c65f5219e1 
Addressed all 4 ask-user findings from the review:

f1: Qualified the MCP access verification claim - noted that it may
contradict infrastructure-update.prose.md and that LiteLLM version may
have been upgraded since that contract was written.

f2: Added key rotation note documenting that MCP headers use literal keys
and do NOT auto-rotate with the vault. Added TODO to consider adding
MCP header regeneration to the Key Update Procedure.

f3: Added MCP server checks to audit-hermes-config.py (Rule 15):
- Validate MCP server URLs against known endpoints
- Check for authentication headers
- Warn if header values look like env-vars instead of literal keys

f4: Updated Rule 15 verification instruction to include MCP initialize
handshake test, not just /v1/models check.

f5: Added NetBird dependency note documenting that 502 errors on MCP
requests may indicate NetBird outage, not auth failure.
fix: add MCP server checks to audit-hermes-config.py
PR Pipeline — Authorize → Validate → Review → Merge / auth (pull_request) Successful in 5s
Details
PR Pipeline — Authorize → Validate → Review → Merge / validate (pull_request) Successful in 7s
Details
PR Pipeline — Authorize → Validate → Review → Merge / lint (pull_request) Successful in 3s
Details
PR Pipeline — Authorize → Validate → Review → Merge / ai-review (pull_request) Successful in 5s
Details
PR Pipeline — Authorize → Validate → Review → Merge / gate (pull_request) Successful in 1s
Details
7400dfd833 
Implement Rule 15 automated enforcement for MCP servers:

- Validate MCP server URLs against known endpoints (ra-h-os, litellm)
- Check for authentication headers on MCP server configs
- Warn if header values look like env-vars instead of literal keys
- Warn if no auth header is present

This ensures the MCP URL/header invariants from the prose contract
are enforced at the earliest shared boundary (before config
application).
mumuni-bot merged commit 1137dd4582 into master 2026-09-17 13:22:32 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
abiba-bot jerome (Jerome Kwame Tabiri) kagentz-bot kwame (Kwame Tabiri) mumuni-bot (Mumuni 🦅 (Syslog Falcon)) tanko-bot theo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: SyslogSolution/prose-contracts#114