Response Handling

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

Code	Description	HTTP Status
`INVALID_REQUEST`	Malformed request	400
`UNAUTHORIZED`	Invalid or missing auth	401
`FORBIDDEN`	Insufficient permissions	403
`NOT_FOUND`	Resource not found	404
`RATE_LIMITED`	Too many requests	429
`INTERNAL_ERROR`	Server error	500
`CREDENTIAL_NOT_FOUND`	Platform credential missing	400
`CONNECTOR_NOT_FOUND`	Invalid connector ID	404
`ACTION_NOT_FOUND`	Invalid action ID	404

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": {...}}

Get Started

Core Concepts

API Reference

AI Integrations

Security

Troubleshooting

Smart Response Management

When You’ll See Different Responses

1. Large Datasets (more than 50 items)

2. Medium Datasets (25-50 items)

3. Normal Responses (less than 25 items)

Why This Matters

Error Responses

Common Error Codes

Error Context

Response Size Management

Automatic Truncation

Elicitation Pattern

Caching

Streaming Responses

​Smart Response Management

​When You’ll See Different Responses

​1. Large Datasets (more than 50 items)

​2. Medium Datasets (25-50 items)

​3. Normal Responses (less than 25 items)

​Why This Matters

​Error Responses

​Common Error Codes

​Error Context

​Response Size Management

​Automatic Truncation

​Elicitation Pattern

​Caching

​Streaming Responses

Smart Response Management

When You’ll See Different Responses

1. Large Datasets (more than 50 items)

2. Medium Datasets (25-50 items)

3. Normal Responses (less than 25 items)

Why This Matters

Error Responses

Common Error Codes

Error Context

Response Size Management

Automatic Truncation

Elicitation Pattern

Caching

Streaming Responses