Skip to main content
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

⌘I