MCP Reliability, Limits, and Error Handling
Last updated:
This page documents MCP runtime protection controls and error patterns.
Scope Enforcement
- Each tool has required scopes resolved at execution time.
- Read defaults to revspire.agentforce.tools.read .
- Mutation defaults to revspire.agentforce.tools.write .
- Equivalent MCP scopes are accepted.
Rate Limiting
Rate limit key is per tool and per viewer in a rolling 60-second window.
Default: 60 requests/min per tool per viewer
Overrides:
- search.query_content: 80/min
- dealroom.create_from_playbook: 20/min
- analytics.chat_grounded: 20/minIdempotency (Mutation Tools)
- Supported on all mutation tools.
- Uses explicit idempotency_key when provided.
- Falls back to deterministic payload hash if key is absent.
- Successful results are replayed for ~10 minutes.
Timeouts
Default timeout: 30s
Overrides:
- search.query_content: 45s
- pitch.get_buyer_journey: 45s
- pitch.create_email_draft: 45s
- analytics.fetch_pitch: 45s
- analytics.chat_grounded: 90s
- dealroom.create_from_playbook: 120sError Model
MCP returns normalized errors with:
- code
- message
- status
- retryable
- details
Common Errors
| Error Code | HTTP | Meaning | Action |
|---|---|---|---|
| TOOL_NOT_FOUND | 404 | Unknown tool name | Check exact tool identifier |
| INVALID_ARGUMENTS | 400 | Schema validation failed | Fix input payload and retry |
| INSUFFICIENT_SCOPE | 403 | Token missing required scope | Reauthorize with required scopes |
| IDENTITY_MISMATCH | 403 | Payload identity conflicts with token | Remove/align viewer and org IDs |
| RATE_LIMITED | 429 | Tool rate limit exceeded | Backoff and retry after delay |
| TOOL_TIMEOUT | 504 | Tool exceeded execution timeout | Retry with narrower query/payload |
| BACKEND_ROUTE_ERROR | 4xx/5xx | Underlying route call failed | Inspect details and source route |
Retry Guidance
- Retryable classes: 408, 425, 429, 500, 502, 503, 504.
- Use exponential backoff with jitter.
- For mutation calls, reuse the same idempotency_key .