API Reference - Alloy Docs

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:

Token URL

No additional headers needed

https://mcp.runalloy.com/mcp/{serverId}/{accessToken}

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

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

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
}

​Base URL

​Authentication

​API Management Endpoints

​MCP Protocol Endpoints

​Server Management API

​Create Server

​List Servers

​Get Server

​Update Server

​Delete Server

​MCP Protocol API

​Required Headers

​With Token URL (Self-sufficient)

​With API Authentication

​Available MCP Tools

​Connectivity Mode Tools (Default)

list_connectors_alloy

get_connector_resources_alloy

get_action_details_alloy

execute_action_alloy

create_credential_alloy

get_credentials_alloy

get_credential_metadata_alloy

discover_action_path_alloy

​Response Handling

​Smart Response Management

​When You’ll See Different Responses

​Why This Matters

​Error Responses

​Common Error Codes

​Rate Limiting

​Input Validation

​Field Limits

​Input Requirements

​Need Help?

Authentication Guide

Quickstart Guide

Use Cases

Available Tools

Base URL

Authentication

API Management Endpoints

MCP Protocol Endpoints

Server Management API

Create Server

List Servers

Get Server

Update Server

Delete Server

MCP Protocol API

Required Headers

With Token URL (Self-sufficient)

With API Authentication

Available MCP Tools

Connectivity Mode Tools (Default)

Response Handling

Smart Response Management

When You’ll See Different Responses

Why This Matters

Error Responses

Common Error Codes

Rate Limiting

Input Validation

Field Limits

Input Requirements

Need Help?