> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getrilo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Integrations

> Create custom API integrations and MCP tools to connect Rilo to any REST API or MCP server.

Custom integrations allow you to connect Rilo to any REST API or MCP server, creating custom tools that work just like built-in integrations. Perfect for internal APIs, specialized services, or APIs not available in Composio.

## Overview

Custom integrations enable you to:

* **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

<Info>
  Custom integrations are a powerful way to extend Rilo's capabilities. Connect to internal tools, specialized services, or any REST API or MCP server.
</Info>

## Integration Types

Rilo supports two types of custom integrations:

<CardGroup cols={2}>
  <Card title="Custom APIs" icon="code">
    Define REST API endpoints manually. Perfect for standard REST APIs with explicit control.
  </Card>

  <Card title="Custom MCP Tools" icon="server">
    Connect to MCP servers for dynamic tool discovery. Ideal for MCP-compatible services.
  </Card>
</CardGroup>

## Custom APIs

Custom APIs allow you to define REST API endpoints manually and create custom tools from them.

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

Specify your API endpoints:

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

Set up authentication:

**API Key:**

```json theme={null}
{
  "auth_type": "api_key",
  "api_key": "your-api-key",
  "header_name": "X-API-Key"
}
```

**Bearer Token:**

```json theme={null}
{
  "auth_type": "bearer",
  "token": "your-bearer-token"
}
```

**OAuth 2.0:**

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

You can add multiple tools to your custom API integration:

**Add Tool via API:**

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

**Add Tool via UI:**

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

Rilo automatically:

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

## Generated Library Structure

### Automatic Generation

Rilo generates a library class from your API definition:

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

Describe what you want:

```
"Get users from my custom API and process them"
```

The AI agent will:

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

### In Generated Code

Custom integrations work like any other library:

```python theme={null}
from library.my_custom_api_tool import MyCustomAPITool

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

## API Definition Best Practices

<AccordionGroup>
  <Accordion title="Clear Endpoint Descriptions">
    Provide clear descriptions for each endpoint. This helps the AI agent understand how to use them.
  </Accordion>

  <Accordion title="Define Request Bodies">
    Specify request body schemas for POST/PUT endpoints. This enables proper parameter handling.
  </Accordion>

  <Accordion title="Document Parameters">
    Document path parameters, query parameters, and headers. This improves code generation.
  </Accordion>

  <Accordion title="Include Examples">
    Include example requests and responses when possible. This helps with testing and validation.
  </Accordion>
</AccordionGroup>

## Authentication Methods

### API Key

Simple API key authentication:

```json theme={null}
{
  "auth_type": "api_key",
  "api_key": "your-key",
  "header_name": "X-API-Key"
}
```

### Bearer Token

Bearer token authentication:

```json theme={null}
{
  "auth_type": "bearer",
  "token": "your-token"
}
```

### OAuth 2.0

OAuth 2.0 flow:

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

Custom header authentication:

```json theme={null}
{
  "auth_type": "custom",
  "headers": {
    "X-Custom-Auth": "your-value"
  }
}
```

<Warning>
  Store API credentials securely. Rilo encrypts sensitive credentials, but you should still follow security best practices.
</Warning>

## Updating Custom Integrations

### Modify Endpoints

You can update custom integrations:

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

<Info>
  Library class names remain stable after initial generation. Only descriptions, capabilities, and limitations can change on regeneration.
</Info>

## Custom MCP Tools

Custom MCP tools allow you to connect to Model Context Protocol (MCP) servers and use their tools in Rilo workflows.

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

Provide MCP server details:

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

**MCP Server Configuration:**

* **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

Rilo automatically:

* 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

MCP servers provide tools dynamically:

* 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

When you add an MCP server, Rilo:

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

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

MCP tools work like any other library:

```python theme={null}
from library.my_mcp_server_tool import MyMCPServerTool

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

### MCP Server Requirements

MCP servers must:

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

### MCP Authentication

MCP servers can use various authentication methods:

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

<Warning>
  Ensure MCP servers handle authentication securely. Never expose sensitive credentials in server URLs or configurations.
</Warning>

### Syncing MCP Tools

You can sync tools from MCP servers:

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

Use custom APIs when:

* ✅ 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

Use custom MCP tools when:

* ✅ 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

<Info>
  Both custom APIs and custom MCP tools achieve similar goals. Choose based on your existing infrastructure and preferences.
</Info>

## Best Practices

<AccordionGroup>
  <Accordion title="Test Before Production">
    Test custom integrations thoroughly before using in production workflows.
  </Accordion>

  <Accordion title="Document APIs">
    Provide clear documentation for your API endpoints. This helps with integration and maintenance.
  </Accordion>

  <Accordion title="Handle Errors">
    Ensure your API returns proper error responses. This helps with debugging and error handling.
  </Accordion>

  <Accordion title="Monitor Usage">
    Monitor API usage and rate limits to ensure workflows run smoothly.
  </Accordion>
</AccordionGroup>

## Managing Custom Integrations

### Adding Tools to API Integrations

You can add multiple tools to a custom API integration:

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

**Tool Configuration:**

* 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

Before using tools in workflows, you can test them:

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

You can update 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

<Info>
  Library class names remain stable after initial generation. Only descriptions, capabilities, and limitations can change on regeneration.
</Info>

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

<Warning>
  Custom integrations are powerful but require proper API or MCP server setup. Ensure your API is well-documented and follows REST conventions, or your MCP server implements the protocol correctly.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Integration not connecting">
    * Verify API base URL is correct
    * Check authentication credentials
    * Ensure API is accessible
    * Test API endpoint directly
  </Accordion>

  <Accordion title="Endpoints not working">
    * Verify endpoint paths are correct
    * Check HTTP methods match API
    * Ensure request bodies match API schema
    * Review API documentation
  </Accordion>

  <Accordion title="Authentication failing">
    * Verify credentials are correct
    * Check authentication method matches API
    * Ensure tokens are valid and not expired
    * Review API authentication documentation
  </Accordion>
</AccordionGroup>

## Related Features

* [MCP Libraries](/integrations/mcp-libraries) - Built-in MCP integration method
* [Integrations Overview](/integrations/overview) - General integration information
* [Email Tools](/integrations/email-tools) - Email integration tools
* [Document Tools](/integrations/document-tools) - Document management tools

***

<Note>
  Custom integrations are a powerful way to extend Rilo's capabilities. Connect to any REST API and use it in your workflows just like built-in integrations.
</Note>