MCP Reliability, Limits, and Error Handling

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/min

Idempotency (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: 120s

Error 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.