feat(mcp): improve MCP docs and increase rate limit to 600 req/min

[brandon-pereira]

Summary

• MCP docs (MCP.md): Added v1/v2 compatibility note, clarified frontend vs backend endpoint paths, replaced outdated OpenCode CLI command with JSON config block, fixed code fence language, and improved wording throughout.
• MCP rate limit: Increased from 100 to 600 requests/min (~10 req/s) per API key to support parallel agent workloads and power users without throttling during traffic spikes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ignored	Preview	May 12, 2026 3:39pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 5a9f043

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/api	Patch
@hyperdx/app	Patch
@hyperdx/otel-collector	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

🔵 Tier 2 — Low Risk

Small, isolated change with no API route or data model modifications.

Why this tier:

• Standard feature/fix — introduces new logic or modifies core functionality

Review process: AI review + quick human skim (target: 5–15 min). Reviewer validates AI assessment and checks for domain-specific concerns.
SLA: Resolve within 4 business hours.

Stats

• Production files changed: 1
• Production lines changed: 2
• Branch: brandon/mcp-tweaks
• Author: brandon-pereira

To override this classification, remove the review/tier-2 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[github-actions]

PR Review

✅ No critical issues found.

• Docs-only changes in MCP.md look correct (v1/v2 note, frontend/backend clarification, valid OpenCode JSON config).
• Rate limit bump 100 → 600 req/min in packages/api/src/mcp/app.ts is straightforward; per-API-key keyGenerator is already in place, so no abuse vector from a single noisy key.
• Changeset (patch on @hyperdx/api) is appropriate for a config tweak.

Minor (non-blocking):

• The OpenCode JSON snippet is a fragment, not a full document — consider wrapping the "mcp": {...} block in { ... } so users can copy-paste a valid file. Not critical since it matches OpenCode's own docs style.

[github-actions]

Deep Review

✅ No critical issues found.

🟡 P2 -- recommended

• packages/api/src/mcp/app.ts:21 -- mcpRateLimiter is mounted before validateUserAccessKey, so the new 600/min ceiling applies to unauthenticated traffic too — rateLimiterKeyGenerator falls back to req.ip (or the shared 'unknown' bucket when IP is absent), and the raised cap lifts the per-IP unauth request ceiling 6× through the auth middleware.
  • Fix: Place mcpRateLimiter after validateUserAccessKey so the raised cap only applies to successfully authenticated keys, or layer a tighter IP-keyed limiter ahead of auth for the unauthenticated path.
  • _{reliability, security}
• packages/api/src/mcp/app.ts:13-19 -- express-rate-limit's default fixed-window store lets a single key admit up to ~1200 requests across a 2-second window-roll boundary, and each authenticated MCP request runs an unbounded ClickHouse query through tool handlers with no per-key in-flight concurrency cap downstream.
  • Fix: Use a sliding-window or token-bucket store, or add a per-key concurrency cap around tool dispatch, so the documented 10 req/s ceiling reflects sustained rate rather than admissible burst.
  • _{performance, reliability}

---

Reviewers (7): correctness, reliability, security, performance, testing, maintainability, project-standards.

[github-actions]

E2E Test Results

✅ All tests passed • 175 passed • 3 skipped • 1243s

Status	Count
✅ Passed	175
❌ Failed	0
⚠️ Flaky	4
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →