> ## 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.

# API Reference

> Complete reference for the Alloy MCP Server API.

<Tip>
  **Interactive API Reference**
  For an interactive API experience with live testing capabilities, visit our [**Interactive API Reference**](/reference/mcp) 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
</Tip>

## Base URL

```
https://mcp.runalloy.com
```

## Authentication

### API Management Endpoints

All server management API requests require authentication:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY  # Required
x-alloy-userid: YOUR_USER_ID        # Optional when using API key
```

Alternative with JWT:

```bash theme={null}
x-alloy-user-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### MCP Protocol Endpoints

Two authentication methods available:

<Steps>
  <Step title="Token URL">
    No additional headers needed

    ```bash theme={null}
    https://mcp.runalloy.com/mcp/{serverId}/{accessToken}
    ```
  </Step>

  <Step title="API Key">
    Requires authentication headers

    ```bash theme={null}
    https://mcp.runalloy.com/mcp/{serverId}
    Authorization: Bearer YOUR_API_KEY
    x-alloy-userid: YOUR_USER_ID
    ```
  </Step>
</Steps>

## Server Management API

### Create Server

Creates a new MCP server instance.

```http theme={null}
POST /api/servers
```

**Headers:**

```bash theme={null}
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:**

```json expandable theme={null}
{
  "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:**

```json expandable theme={null}
{
  "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.

```http theme={null}
GET /api/servers
```

**Headers:**

```bash theme={null}
Authorization: Bearer YOUR_API_KEY  # Required
x-alloy-userid: YOUR_USER_ID        # Optional (defaults to API key's user)
```

**Response:**

```json theme={null}
{
  "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.

```http theme={null}
GET /api/servers/:serverId
```

**Headers:**

```bash theme={null}
Authorization: Bearer YOUR_API_KEY  # Required
x-alloy-userid: YOUR_USER_ID        # Optional (defaults to API key's user)
```

**Response:**

```json expandable theme={null}
{
  "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.

```http theme={null}
PUT /api/servers/:serverId
```

**Headers:**

```bash theme={null}
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:**

```json theme={null}
{
  "name": "string",
  "description": "string",
  "isPublic": boolean,
  "restrictions": {}
}
```

**Response:**

```json theme={null}
{
  "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.

```http theme={null}
DELETE /api/servers/:serverId
```

**Headers:**

```bash theme={null}
Authorization: Bearer YOUR_API_KEY  # Required
x-alloy-userid: YOUR_USER_ID        # Optional (defaults to API key's user)
```

**Response:**

```json theme={null}
{
  "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

```http theme={null}
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)

```http theme={null}
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.

```http theme={null}
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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json expandable theme={null}
{
  "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.

```json expandable theme={null}
{
  "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.

```json expandable theme={null}
{
  "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.

```json expandable theme={null}
{
  "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.

```json expandable theme={null}
{
  "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:

```json expandable theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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?

<CardGroup>
  <Card title="Authentication Guide" href="/mcp/security/authentication-security" icon="lock" iconType="solid" horizontal />

  <Card title="Quickstart Guide" href="/mcp/getting-started/quickstart" icon="rocket" iconType="solid" horizontal />

  <Card title="Use Cases" href="/mcp/use-cases/industry-solutions" icon="lightbulb" iconType="solid" horizontal />

  <Card title="Available Tools" href="/mcp/api-reference/available-tools" icon="code" iconType="solid" horizontal />
</CardGroup>