Skip to main content

​
Smart Response Management

The MCP Server automatically optimizes large responses for better performance and usability.

​
When You’ll See Different Responses

​
1. Large Datasets (more than 50 items)

Instead of overwhelming the MCP client with hundreds of results, the server returns helpful guidance: 
{
  "needsRefinement": true,
  "message": "Found 298 users. This is too many to display effectively.",
  "guidance": "When dealing with large result sets, it's better to:\n1. Search for specific items by name or ID\n2. Use filtering parameters\n3. Paginate through results",
  "suggestions": [
    "Try: users_list with limit parameter (e.g., { limit: 10 })",
    "Search for specific users by email",
    "Filter by status or creation date"
  ],
  "searchInstructions": "You can search using:\n- query (query): Search by name\n- limit (query): Limit results (e.g., 10)",
  "samples": [
    { "id": "U123", "name": "John Doe", "email": "john@example.com" },
    { "id": "U124", "name": "Jane Smith", "email": "jane@example.com" }
  ]
}

​
2. Medium Datasets (25-50 items)

Automatically limited with metadata: 
{
  "data": [ /* First 25 items */ ],
  "metadata": {
    "originalCount": 45,
    "displayedCount": 25,
    "truncated": true,
    "paginationHint": "Showing first 25 of 45 items."
  }
}

​
3. Normal Responses (less than 25 items)

Standard response with full data.

​
Why This Matters

  • Better Performance: Faster responses, less data transfer
  • Smarter Interactions: The AI guides you to refine searches
  • Platform Limits: Respects rate limits of external APIs

​
Error Responses

All errors follow a consistent format: 
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional context"
    }
  }
}

​
Common Error Codes

CodeDescriptionHTTP Status
INVALID_REQUESTMalformed request400
UNAUTHORIZEDInvalid or missing auth401
FORBIDDENInsufficient permissions403
NOT_FOUNDResource not found404
RATE_LIMITEDToo many requests429
INTERNAL_ERRORServer error500
CREDENTIAL_NOT_FOUNDPlatform credential missing400
CONNECTOR_NOT_FOUNDInvalid connector ID404
ACTION_NOT_FOUNDInvalid action ID404

​
Error Context

Errors include contextual information to help debug issues: 
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Credential not found for Slack",
    "data": {
      "connectorId": "slack",
      "suggestion": "Run get_credentials_alloy('slack') to check available credentials",
      "authUrl": "https://app.runalloy.com/oauth/slack"
    }
  },
  "id": 1
}

​
Response Size Management

​
Automatic Truncation

To prevent overwhelming responses:
  • Arrays: Limited to 25 items by default
  • Strings: Truncated at 5KB with ellipsis
  • Nested objects: Deep nesting limited to 10 levels

​
Elicitation Pattern

For large datasets, the server provides guidance instead of raw data: 
{
  "type": "elicitation",
  "totalItems": 500,
  "message": "Too many results to display. Please refine your search.",
  "availableFilters": ["status", "created_date", "name"],
  "examples": [
    "Search by name: {\"name\": \"John\"}",
    "Filter by status: {\"status\": \"active\"}",
    "Limit results: {\"limit\": 10}"
  ]
}

​
Caching

Responses are cached for improved performance:
  • Cache TTL: 1 hour for read operations
  • Cache Key: Based on connector, action, and parameters
  • Cache Invalidation: Automatic on write operations
  • Cache Headers: X-Cache-Hit: true when served from cache

​
Streaming Responses

For long-running operations, the server supports streaming: 
Accept: text/event-stream
Streaming events: 
event: progress
data: {"message": "Processing item 1 of 100"}

event: result
data: {"status": "complete", "result": {...}}
⌘I