Custom Integrations

​

Overview

• Connect to any REST API: No limitations on API structure
• Connect to MCP servers: Use Model Context Protocol servers for custom tools
• Generate libraries automatically: Rilo creates Python libraries from your API or MCP definition
• Use in workflows: Custom tools work like built-in integrations
• Reuse across workflows: Create once, use everywhere

​

Integration Types

​

Custom APIs

​

Creating Custom API Integrations

​

Step 1: Navigate to Integrations

1. Go to the Integrations page
2. Find the Custom Integrations section
3. Click “Create Custom Integration”
4. Select “API” as the integration type

​

Step 2: Define API Endpoints

{
  "name": "My Custom API",
  "base_url": "https://api.example.com/v1",
  "endpoints": [
    {
      "path": "/users",
      "method": "GET",
      "description": "Get list of users"
    },
    {
      "path": "/users/{id}",
      "method": "GET",
      "description": "Get user by ID"
    },
    {
      "path": "/users",
      "method": "POST",
      "description": "Create new user",
      "body_schema": {
        "name": "string",
        "email": "string"
      }
    }
  ]
}

​

Step 3: Configure Authentication

{
  "auth_type": "api_key",
  "api_key": "your-api-key",
  "header_name": "X-API-Key"
}

{
  "auth_type": "bearer",
  "token": "your-bearer-token"
}

{
  "auth_type": "oauth2",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "token_url": "https://api.example.com/oauth/token"
}

​

Step 4: Add Tools

POST /api/v2/integrations/{integration_id}/add_tool/
{
  "name": "get_user",
  "description": "Get user by ID",
  "method": "GET",
  "url": "https://api.example.com/v1/users/{id}",
  "auth_type": "bearer",
  "auth_config": {
    "token": "your-token"
  },
  "query_params": [
    {"key": "include", "value": "profile"}
  ],
  "headers": [
    {"key": "X-Custom-Header", "value": "value"}
  ]
}

1. Go to your custom integration details page
2. Click “Add Tool”
3. Fill in tool details:
   • Name and description
   • HTTP method (GET, POST, PUT, PATCH, DELETE)
   • URL endpoint
   • Authentication configuration
   • Query parameters, headers, and body parameters
4. Test the tool before saving
5. Save the tool

​

Step 5: Generate Library

• Generates a Python library class
• Creates methods for each tool/endpoint
• Handles authentication
• Makes tools available in workflows

​

Generated Library Structure

​

Automatic Generation

class MyCustomAPITool(BaseTool):
    """
    My Custom API
    
    Custom integration for api.example.com
    """
    
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.base_url = "https://api.example.com/v1"
        self.api_key = "your-api-key"
    
    def get_users(self, **kwargs):
        """Get list of users"""
        return self._make_request("GET", "/users", **kwargs)
    
    def get_user_by_id(self, user_id, **kwargs):
        """Get user by ID"""
        return self._make_request("GET", f"/users/{user_id}", **kwargs)
    
    def create_user(self, name, email, **kwargs):
        """Create new user"""
        return self._make_request("POST", "/users", 
            body={"name": name, "email": email}, **kwargs)

​

Using Custom Integrations

​

Via Natural Language

"Get users from my custom API and process them"

• Identify your custom integration
• Use it in generated code
• Handle authentication automatically

​

In Generated Code

from library.my_custom_api_tool import MyCustomAPITool

api = MyCustomAPITool()
users = api.get_users()
for user in users:
    # Process user
    ...

​

API Definition Best Practices

​

Authentication Methods

​

API Key

{
  "auth_type": "api_key",
  "api_key": "your-key",
  "header_name": "X-API-Key"
}

​

Bearer Token

{
  "auth_type": "bearer",
  "token": "your-token"
}

​

OAuth 2.0

{
  "auth_type": "oauth2",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "authorization_url": "https://api.example.com/oauth/authorize",
  "token_url": "https://api.example.com/oauth/token",
  "scopes": ["read", "write"]
}

​

Custom Headers

{
  "auth_type": "custom",
  "headers": {
    "X-Custom-Auth": "your-value"
  }
}

​

Updating Custom Integrations

​

Modify Endpoints

1. Go to Integrations page: Find your custom integration
2. Click “Edit”: Modify endpoint definitions
3. Regenerate: Rilo regenerates the library
4. Update Workflows: Existing workflows use the updated integration

​

Custom MCP Tools

​

Creating Custom MCP Integration

​

Step 1: Navigate to Integrations

1. Go to the Integrations page
2. Find the Custom Integrations section
3. Click “Create Custom Integration”
4. Select “MCP” as the integration type

​

Step 2: Configure MCP Server

{
  "name": "My Custom MCP Server",
  "mcp_server_url": "https://mcp.example.com/api/mcp",
  "mcp_server_name": "My MCP Service",
  "mcp_auth_type": "bearer",
  "mcp_auth_config": {
    "token": "your-api-token"
  }
}

• Server URL: The MCP server endpoint (must be publicly accessible)
• Server Name: Optional name for the MCP service
• Auth Type: Authentication method (none, bearer, api_key)
• Auth Config: Authentication credentials (encrypted by Rilo)

​

Step 3: Connect and Discover Tools

• Tests the connection to the MCP server
• Fetches available tools from the server
• Generates a Python library class
• Creates methods for each MCP tool
• Makes tools available in workflows

​

Step 4: Tool Discovery

• Tools are discovered from the MCP server
• Each tool becomes a method in the generated library
• Tool descriptions and parameters are extracted automatically
• Tools can be refreshed by syncing with the MCP server

​

MCP Tool Generation

1. Connects to server: Establishes connection with authentication
2. Fetches tools: Gets available tools from the server
3. Generates class: Creates a Python library class
4. Creates methods: Each MCP tool becomes a method
5. Enhances metadata: Uses AI to improve tool descriptions

​

Generated MCP Library Structure

class MyMCPServerTool(BaseTool):
    """
    My Custom MCP Server
    
    Tools are executed via the MCP protocol.
    """
    
    IS_MCP_LIBRARY = True
    
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.mcp_server_url = "https://mcp.example.com/api/mcp"
    
    def tool_method_1(self, param1, param2):
        """Execute tool_method_1 via MCP"""
        return self._call_mcp_tool("tool_method_1", {
            "param1": param1,
            "param2": param2
        })

​

Using Custom MCP Tools

from library.my_mcp_server_tool import MyMCPServerTool

mcp_tool = MyMCPServerTool()
result = mcp_tool.tool_method_1(
    param1="value1",
    param2="value2"
)

​

MCP Server Requirements

• ✅ Implement the MCP protocol
• ✅ Be accessible via HTTP/HTTPS
• ✅ Support tool discovery
• ✅ Handle tool execution requests
• ✅ Return results in MCP format

​

MCP Authentication

• Bearer Token: API key in Authorization header
• API Key: Key in headers or query parameters
• None: No authentication required

​

Syncing MCP Tools

1. Go to your MCP integration details page
2. Click “Sync Tools” to refresh available tools
3. Rilo will fetch latest tools from the server
4. New tools are automatically added to the library

​

Custom API vs Custom MCP

​

When to Use Custom APIs

• ✅ You have a standard REST API
• ✅ You want direct HTTP integration
• ✅ You prefer explicit API definitions
• ✅ You need custom authentication flows
• ✅ You want full control over tool definitions

​

When to Use Custom MCP Tools

• ✅ You have an existing MCP server
• ✅ You want to leverage MCP protocol features
• ✅ You need dynamic tool discovery
• ✅ Tools are provided by an MCP-compatible service
• ✅ You want automatic tool synchronization

​

Best Practices

​

Managing Custom Integrations

​

Adding Tools to API Integrations

1. Via UI: Use the “Add Tool” button in the integration details page
2. Via API: Use the /add_tool/ endpoint to programmatically add tools

• Name and description
• HTTP method (GET, POST, PUT, PATCH, DELETE)
• URL endpoint with path parameters
• Authentication configuration
• Query parameters
• Headers
• Body parameters (for POST/PUT/PATCH)
• Sample response (optional)

​

Testing Tools

1. Go to tool details in your integration
2. Click “Test Tool”
3. Provide test parameters
4. Execute the tool
5. Review the response

​

Updating Custom Integrations

1. Go to Integrations page: Find your custom integration
2. Click “Edit”: Modify integration details
3. For API integrations: Add, edit, or remove tools
4. For MCP integrations: Update server URL or authentication
5. Regenerate: Rilo regenerates the library if needed
6. Update Workflows: Existing workflows use the updated integration

​

Limitations

​

Custom API Limitations

• REST APIs only: Currently supports REST APIs, not GraphQL or other protocols
• Manual definition: Must manually define endpoints (no auto-discovery)
• No webhooks: Custom integrations don’t support webhook triggers (use app events)
• Rate limits: Subject to API rate limits

​

Custom MCP Limitations

• MCP protocol required: Server must implement MCP protocol
• Public accessibility: Server must be accessible from Rilo’s infrastructure
• Tool discovery: Depends on MCP server’s tool discovery implementation
• Rate limits: Subject to MCP server rate limits

​

Troubleshooting

​

Related Features

• MCP Libraries - Built-in MCP integration method
• Integrations Overview - General integration information
• Email Tools - Email integration tools
• Document Tools - Document management tools