Restrictions Guide - Alloy Docs

What Are Restrictions?

Restrictions are security rules that limit what an MCP server can access. Think of them as a firewall for your AI assistant - they define:

Which platforms (connectors) the AI can use
Which actions the AI can perform on each platform
Which users can access the server

Without restrictions, an MCP server has access to all connectors and all their actions. With restrictions, you create a secure boundary around what the AI assistant can do.

How Restrictions Work

When you create an MCP server with restrictions, the system filters responses at multiple levels: The restriction system works in layers:

Connector Discovery - When the AI lists available connectors, it only sees the ones you allowed
Action Discovery - When exploring a connector’s capabilities, it only sees permitted actions
Action Execution - Attempts to use blocked actions are rejected with an error
Credential Management - Can only create/view credentials for allowed connectors

This creates a complete security perimeter - the AI literally cannot see or access anything outside your defined boundaries.

Why Use Restrictions?

Security & Compliance

Data Protection: Ensure AI only accesses approved systems
Compliance: Meet regulatory requirements by limiting data access

Business Logic

Department Isolation: Sales team only sees CRM tools, Marketing only sees email tools
Read-Only Access: Allow viewing data but prevent modifications
Staged Rollouts: Test AI with limited access before full deployment

Error Prevention

No Accidents: Can’t accidentally delete data if delete actions are blocked
Clear Boundaries: AI knows exactly what it can and cannot do
User Safety: Prevent costly mistakes before they happen

Visualizing the Impact

Without Restrictions - AI Sees Everything:

With Restrictions - AI Sees Only What You Allow:

Quick Examples

Example 1: Slack Read-Only

“Only allow reading user information from Slack”

{
  "name": "Slack Users Reader",
  "restrictions": {
    "permissions": [
      {
        "connector": "slack",
        "mode": "allow",
        "actions": ["users_list", "users_info"]
      }
    ]
  }
}

Example 2: Multi-Platform with Specific Actions

“Different permissions for each platform”

{
  "name": "Multi-Platform Assistant",
  "restrictions": {
    "permissions": [
      {
        "connector": "slack",
        "mode": "allow",
        "actions": ["chat_postMessage", "users_list"]
      },
      {
        "connector": "notion",
        "mode": "allow",
        "actions": ["pages_create", "pages_retrieve", "pages_update"]
      },
      {
        "connector": "hubspot",
        "mode": "allow",
        "actions": ["contacts_list", "contacts_get"]
      }
    ]
  }
}

You can test these quick examples out with the Update Server endpoint. We’ll also cover more information about restrictions in the following section.

How Restrictions Work

Understanding the Restrictions Structure

The JSON Structure

{
  "restrictions": {
    "permissions": [
      {
        "connector": "slack",        // Which platform
        "mode": "allow",             // Always "allow"
        "actions": ["users_list"]    // Which actions (or ["*"] for all)
      }
    ]
  }
}

Key Components Explained

`permissions` Array

Contains rules for each connector you want to allow. If a connector isn’t listed here, the AI cannot access it at all.

`connector` Field

The ID of the platform (e.g., “slack”, “notion”, “hubspot”). Get these IDs from the list connectors endpoint.

`mode` Field

Always set to "allow". This explicitly grants access to the specified connector and actions.

`actions` Array

Lists the specific actions allowed for this connector:

Specific actions: ["users_list", "users_info"] - Only these actions allowed
All actions: ["*"] - All actions for this connector allowed
Empty array: [] - No actions allowed (connector visible but unusable)

How the Filtering Works

When restrictions are applied, the system:

Hides unlisted connectors - If not in permissions, connector doesn’t exist for the AI
Filters action lists - Only shows actions you specified in the actions array
Blocks unauthorized attempts - Returns errors if AI tries blocked actions
Restricts credential creation - Can only create credentials for allowed connectors

2. User Restrictions

Control who can access the server. You can manage your users with these endpoints. Allowlist specific users:

{
  "users": {
    "mode": "allowlist",
    "allowedUserIds": ["user_123", "user_456"]
  }
}

Common Slack Actions Reference

When restricting Slack, here are the available actions:

chat_postMessage - Send messages
conversations_create - Create channels
conversations_invite - Invite users to channels
conversations_list - List channels
users_conversations - List user’s channels
users_info - Get user information
users_list - List all users

Implementation Examples

Creating a Restricted Server with Fine-Grained Permissions

curl -X POST https://mcp.runalloy.com/api/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Secure Assistant",
    "description": "Limited access with specific actions",
    "restrictions": {
      "permissions": [
        {
          "connector": "slack",
          "mode": "allow",
          "actions": ["users_list", "users_info", "chat_postMessage"]
        },
        {
          "connector": "notion",
          "mode": "allow",
          "actions": ["pages_retrieve", "databases_retrieve"]
        },
        {
          "connector": "hubspot",
          "mode": "allow",
          "actions": ["contacts_list", "contacts_get"]
        }
      ]
    }
  }'

Read-Only Server Example

curl -X POST https://mcp.runalloy.com/api/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Read-Only Assistant",
    "description": "Can only read data, no write operations",
    "restrictions": {
      "permissions": [
        {
          "connector": "slack",
          "mode": "allow",
          "actions": ["users_list", "users_info", "conversations_list"]
        },
        {
          "connector": "notion",
          "mode": "allow",
          "actions": ["pages_retrieve", "databases_retrieve", "blocks_retrieve"]
        }
      ]
    }
  }'

Updating Restrictions

curl -X PUT https://mcp.runalloy.com/api/servers/YOUR_SERVER_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "restrictions": {
      "connectors": {
        "mode": "allowlist",
        "allowedIds": ["slack", "notion"]
      }
    }
  }'

How Restrictions Work

Multi-Level Filtering

The restriction system now applies filters at multiple points:

list_connectors_alloy - Returns only allowed connectors
get_connector_resources_alloy - Returns only allowed actions per connector
get_action_details_alloy - Blocks access to restricted action details
execute_action_alloy - Prevents execution of restricted actions
create_credential_alloy - Blocks credential creation for restricted connectors

This ensures the AI assistant only sees and can interact with what’s explicitly permitted.

Best Practices

1. Start Restrictive

Begin with maximum restrictions and loosen as needed:

{
  "permissions": []  // Start with no permissions
}

2. Test Before Production

Always test restrictions in a development environment:

# Create test server
curl -X POST https://mcp.runalloy.com/api/servers \
  -H "Authorization: Bearer DEV_API_KEY" \
  -d '{"name": "Test Restrictions", "restrictions": {...}}'

# Test with your MCP client
# "Try to access Slack" -> Should fail if blocked

3. Document Your Restrictions

Keep a record of why each restriction exists in your internal documentation.

Troubleshooting

”Access Denied” Errors

Error: Access denied: connector 'hubspot' is restricted Solution: Check your restrictions:

curl -X GET https://mcp.runalloy.com/api/servers/YOUR_SERVER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Testing Restrictions

Test your restrictions with these commands:

# 1. Test connector filtering
curl -X POST "YOUR_SERVER_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_connectors_alloy",
      "arguments": {}
    },
    "id": "1"
  }'

# 2. Test action filtering
curl -X POST "YOUR_SERVER_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_connector_resources_alloy",
      "arguments": {"connectorId": "slack"}
    },
    "id": "1"
  }'

# 3. Test blocked action
curl -X POST "YOUR_SERVER_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_action_details_alloy",
      "arguments": {
        "connectorId": "slack",
        "actionId": "conversations_create"
      }
    },
    "id": "1"
  }'

Or ask your AI assistant:

"List available connectors"
"What Slack actions can I use?"
"Try to create a Slack channel" (should fail if not allowed)

Getting started

Core Concepts

API Reference

AI Integrations

Security

Troubleshooting

​What Are Restrictions?

​How Restrictions Work

​Why Use Restrictions?

​Security & Compliance

​Business Logic

​Error Prevention

​Visualizing the Impact

​Without Restrictions - AI Sees Everything:

​With Restrictions - AI Sees Only What You Allow:

​Quick Examples

​Example 1: Slack Read-Only

​Example 2: Multi-Platform with Specific Actions

​How Restrictions Work

​Understanding the Restrictions Structure

​The JSON Structure

​Key Components Explained

​permissions Array

​connector Field

​mode Field

​actions Array

​How the Filtering Works

​2. User Restrictions

​Common Slack Actions Reference

​Implementation Examples

​Creating a Restricted Server with Fine-Grained Permissions

​Read-Only Server Example

​Updating Restrictions

​How Restrictions Work

​Multi-Level Filtering

​Best Practices

​1. Start Restrictive

​2. Test Before Production

​3. Document Your Restrictions

​Troubleshooting

​”Access Denied” Errors

​Testing Restrictions

​Additional Resources

API Reference

Authentication Guide

What Are Restrictions?

How Restrictions Work

Why Use Restrictions?

Security & Compliance

Business Logic

Error Prevention

Visualizing the Impact

Without Restrictions - AI Sees Everything:

With Restrictions - AI Sees Only What You Allow:

Quick Examples

Example 1: Slack Read-Only

Example 2: Multi-Platform with Specific Actions

How Restrictions Work

Understanding the Restrictions Structure

The JSON Structure

Key Components Explained

`permissions` Array

`connector` Field

`mode` Field

`actions` Array

How the Filtering Works

2. User Restrictions

Common Slack Actions Reference

Implementation Examples

Creating a Restricted Server with Fine-Grained Permissions

Read-Only Server Example

Updating Restrictions

How Restrictions Work

Multi-Level Filtering

Best Practices

1. Start Restrictive

2. Test Before Production

3. Document Your Restrictions

Troubleshooting

”Access Denied” Errors

Testing Restrictions

Additional Resources