Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt

Use this file to discover all available pages before exploring further.

Interactive API Reference For an interactive API experience with live testing capabilities, visit our Interactive API Reference where you can:
  • Test API endpoints directly in your browser
  • View detailed request/response examples
  • Generate code snippets in multiple languages
  • Explore the full API schema

​
Base URL

https://mcp.runalloy.com

​
Authentication

​
API Management Endpoints

All server management API requests require authentication: 
Authorization: Bearer YOUR_API_KEY  # Required
x-alloy-userid: YOUR_USER_ID        # Optional when using API key
Alternative with JWT: 
x-alloy-user-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

​
MCP Protocol Endpoints

Two authentication methods available:
1

Token URL

No additional headers needed
https://mcp.runalloy.com/mcp/{serverId}/{accessToken}
2

API Key

Requires authentication headers
https://mcp.runalloy.com/mcp/{serverId}
Authorization: Bearer YOUR_API_KEY
x-alloy-userid: YOUR_USER_ID

​
Server Management API

​
Create Server

Creates a new MCP server instance. 
POST /api/servers
Headers: 
Authorization: Bearer YOUR_API_KEY  # Required
x-alloy-userid: YOUR_USER_ID        # Optional (defaults to API key's user)
Content-Type: application/json       # Required for POST/PUT
Request Body: 
{
  "name": "string",
  "description": "string",
  "isPublic": boolean,
  "tokenExpiresInDays": number,
  "restrictions": {
    "connectors": {
      "mode": "allowlist" | "blocklist",
      "allowedIds": ["string"],
      "blockedIds": ["string"]
    },
    "actions": {
      "mode": "allowlist" | "blocklist",
      "allowedActions": ["string"],
      "blockedActions": ["string"]
    },
    "users": {
      "mode": "allowlist" | "blocklist",
      "allowedIds": ["string"],
      "blockedIds": ["string"]
    }
  }
}
Response: 
{
  "serverId": "my-server-a1b2c3d4",
  "name": "My Server",
  "description": "Server description",
  "mode": "connectivity",
  "isPublic": false,
  "accessToken": "mcp_token_xyz789",
  "url": "https://mcp.runalloy.com/mcp/my-server-a1b2c3d4",
  "accessUrl": "https://mcp.runalloy.com/mcp/my-server-a1b2c3d4/mcp_token_xyz789",
  "restrictions": {},
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

​
List Servers

Lists all servers for the authenticated user. 
GET /api/servers
Headers: 
Authorization: Bearer YOUR_API_KEY  # Required
x-alloy-userid: YOUR_USER_ID        # Optional (defaults to API key's user)
Response: 
{
  "servers": [
    {
      "serverId": "production-server-a1b2c3d4",
      "name": "Production Server",
      "description": "Main production MCP server",
      "url": "https://mcp.runalloy.com/mcp/production-server-a1b2c3d4",
      "accessUrl": "https://mcp.runalloy.com/mcp/production-server-a1b2c3d4/mcp_token_xyz789",
      "isPublic": false,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "count": 15
}

​
Get Server

Retrieves details for a specific server. 
GET /api/servers/:serverId
Headers: 
Authorization: Bearer YOUR_API_KEY  # Required
x-alloy-userid: YOUR_USER_ID        # Optional (defaults to API key's user)
Response: 
{
  "serverId": "production-server-a1b2c3d4",
  "name": "Production Server",
  "description": "Main production MCP server",
  "url": "https://mcp.runalloy.com/mcp/production-server-a1b2c3d4",
  "accessUrl": "https://mcp.runalloy.com/mcp/production-server-a1b2c3d4/mcp_token_xyz789",
  "isPublic": false,
  "hasRestrictions": true,
  "restrictions": {
    "connectors": {
      "mode": "allowlist",
      "allowedIds": ["slack", "hubspot"]
    }
  },
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

​
Update Server

Updates server configuration. 
PUT /api/servers/:serverId
Headers: 
Authorization: Bearer YOUR_API_KEY  # Required
x-alloy-userid: YOUR_USER_ID        # Optional (defaults to API key's user)
Content-Type: application/json       # Required for POST/PUT
Request Body: 
{
  "name": "string",
  "description": "string",
  "isPublic": boolean,
  "restrictions": {}
}
Response: 
{
  "serverId": "production-server-a1b2c3d4",
  "name": "Updated Server Name",
  "description": "Updated description",
  "updatedAt": "2024-01-01T00:00:00Z"
}

​
Delete Server

Deletes a server and all associated data. 
DELETE /api/servers/:serverId
Headers: 
Authorization: Bearer YOUR_API_KEY  # Required
x-alloy-userid: YOUR_USER_ID        # Optional (defaults to API key's user)
Response: 
{
  "message": "Server deleted",
  "serverId": "production-server-a1b2c3d4"
}
Error Responses:
  • 401 Unauthorized - Invalid or missing authentication
  • 403 Forbidden - Not authorized to delete this server
  • 404 Not Found - Server not found

​
MCP Protocol API

The MCP protocol endpoints accept standard MCP JSON-RPC requests.

​
Required Headers

Content-Type: application/json
Accept: application/json, text/event-stream
Important: These headers are REQUIRED. Without the Accept header including text/event-stream, you will receive a 406 Not Acceptable error.

​
With Token URL (Self-sufficient)

POST /mcp/:serverId/:accessToken
GET /mcp/:serverId/:accessToken
Required Headers:
  • Content-Type: application/json
  • Accept: application/json, text/event-stream
Optional Headers:
  • x-alloy-user-token: JWT token for user isolation
  • x-alloy-userid: Override user ID (public servers only)
  • x-credential-id: Use specific credential for operations
  • x-redirect-uri: OAuth redirect URI for credential creation

​
With API Authentication

Requires standard API authentication headers. 
POST /mcp/:serverId
GET /mcp/:serverId
Required Headers:
  • Content-Type: application/json
  • Accept: application/json, text/event-stream
  • Authorization: Bearer YOUR_API_KEY
  • x-alloy-userid: Your user ID
Optional Headers:
  • x-alloy-user-token: JWT token for user isolation
  • x-credential-id: Use specific credential for operations
  • x-redirect-uri: OAuth redirect URI for credential creation
  • x-mcp-server-id: Alternative way to specify server ID

​
Available MCP Tools

​
Connectivity Mode Tools (Default)

list_connectors_alloy
Lists all available platform connectors. 
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_connectors_alloy",
    "arguments": {
      "category": "communication"
    }
  },
  "id": 1
}
get_connector_resources_alloy
Gets available resources and actions for a connector. 
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_connector_resources_alloy",
    "arguments": {
      "connectorId": "slack"
    }
  },
  "id": 1
}
get_action_details_alloy
Gets detailed parameter information for an action. 
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_action_details_alloy",
    "arguments": {
      "connectorId": "slack",
      "actionId": "chat_postMessage"
    }
  },
  "id": 1
}
execute_action_alloy
Executes an action on a platform. 
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "execute_action_alloy",
    "arguments": {
      "connectorId": "slack",
      "actionId": "chat_postMessage",
      "parameters": {
        "channel": "C1234567890",
        "text": "Hello from MCP!"
      },
      "credentialId": "cred_abc123"
    }
  },
  "id": 1
}
create_credential_alloy
Creates new platform credentials. 
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create_credential_alloy",
    "arguments": {
      "connectorId": "slack",
      "authenticationType": "oauth2",
      "redirectUri": "https://app.runalloy.com/oauth/callback",
      "fields": {}
    }
  },
  "id": 1
}
get_credentials_alloy
Lists existing credentials for a connector. 
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_credentials_alloy",
    "arguments": {
      "connectorId": "slack"
    }
  },
  "id": 1
}
get_credential_metadata_alloy
Gets supported authentication types and required fields. 
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_credential_metadata_alloy",
    "arguments": {
      "connectorId": "slack"
    }
  },
  "id": 1
}
discover_action_path_alloy
Provides workflow guidance for achieving specific goals. 
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "discover_action_path_alloy",
    "arguments": {
      "connectorId": "slack",
      "goal": "send message to channel"
    }
  },
  "id": 1
}

​
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

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

​
Rate Limiting

Default Limit: 100 requests per minute per API key/token Implementation: Token bucket algorithm with 60-second sliding window Configuration: Set via RATE_LIMIT_PER_MINUTE environment variable Rate Limit Exceeded Response (429 Too Many Requests): 
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Rate limit exceeded. Please try again later."
  },
  "id": null
}

​
Input Validation

​
Field Limits

  • Server name: 1-100 characters
  • Token expiration: 1-365 days
  • Request body size: 10MB maximum
  • Array limits: 1000 items maximum in responses

​
Input Requirements

  • Server name: Must be unique per user
  • User ID: Your unique identifier from Alloy
  • API Key: Provided by Alloy

​
Need Help?

Authentication Guide

Quickstart Guide

Use Cases

Available Tools