Composio Rust SDK

Type-safe, async Rust SDK for Composio’s Tool Router and API v3.

Overview

Composio helps AI apps and agents connect to external services through a unified API.
This SDK gives Rust developers a strongly-typed client for sessions, tools, auth flows, MCP servers, files, and trigger-related APIs.

What's New in v0.3.0

This release significantly expands API parity and lifecycle coverage:

• Added full MCP server management support (create/get/update/delete/list/generate/custom).
• Added project configuration endpoints (get_project_config, update_project_config).
• Added CLI session endpoints (create_cli_session, get_cli_session).
• Added migration helper endpoint (get_migration_nanoid).
• Added tools enum endpoint (retrieve_tool_enum).
• Added trigger types enum endpoint (retrieve_trigger_type_enum).
• Added toolkit retrieve version support via get_toolkit_with_params.
• Added connected account lifecycle endpoints (refresh/status/delete).
• Added auth config lifecycle endpoints (get/update/delete/status update).
• Added direct link endpoint parity (create_connected_account_link).
• Added files API parity improvements (list_files, create_file_upload_request) and aligned file models.

Features

• Tool execution: list/retrieve/execute/proxy tools and generate tool inputs.
• Tool Router sessions: create per-user sessions and execute tools in session context.
• MCP servers: create, list, retrieve, update, delete, and generate MCP server URLs.
• Connected accounts: list/retrieve/link/refresh/update-status/delete connected accounts.
• Auth configs: list/create/retrieve/update/delete auth configs and update status.
• Files: list files, request upload URLs, and use upload/download helper abstractions.
• CLI sessions: create and retrieve CLI authentication sessions.
• Migration helper: convert legacy UUIDs to NanoIDs.
• Project config: retrieve and update project-level configuration.
• Triggers: list/retrieve trigger types, retrieve trigger enums, and work with trigger instances.

Installation

cargo add composio-sdk

Or add manually:

[dependencies]
composio-sdk = "0.3"
tokio = { version = "1", features = ["full"] }
serde_json = "1"

Quick Start

Minimal end-to-end flow:

use composio_sdk::client::ComposioClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ComposioClient::builder()
        .api_key(std::env::var("COMPOSIO_API_KEY")?)
        .build()?;

    // 1) Create a user-scoped Tool Router session
    let session = client
        .create_session("user_123")
        .toolkits(vec!["github"])
        .send()
        .await?;

    // 2) Execute a tool via that session
    let result = session
        .execute_tool(
            "GITHUB_CREATE_ISSUE",
            serde_json::json!({
                "owner": "acme",
                "repo": "demo",
                "title": "Issue from Rust SDK"
            }),
        )
        .await?;

    println!("success: {}", result.successful);
    Ok(())
}

Authentication

Use your Composio API key (sent as x-api-key):

let client = composio_sdk::client::ComposioClient::builder()
    .api_key(std::env::var("COMPOSIO_API_KEY")?)
    .build()?;

Core Concepts

Tools

Use list_tools, get_tool, execute_tool, generate_tool_inputs, proxy_tool, and retrieve_tool_enum.

Tool Router

Create sessions with create_session(...).send(), then execute tools and meta tools per user context.

MCP Servers

Use create_mcp_server, list_mcp_servers, get_mcp_server, update_mcp_server, delete_mcp_server, generate_mcp_server, and related methods.

Connected Accounts

Use list_connected_accounts, get_connected_account, create_connected_account_link, refresh_connected_account, update_connected_account_status, and delete_connected_account.

Auth Configs

Use list_auth_configs, create_auth_config, get_auth_config, update_auth_config, delete_auth_config, and update_auth_config_status.

Files

Use endpoint wrappers (list_files, create_file_upload_request) or helper abstractions (FileUploadable, FileDownloadable, FileHelper).

CLI Sessions

Use create_cli_session and get_cli_session for CLI auth workflows.

Migration

Use get_migration_nanoid for UUID → NanoID migration lookups.

Project Config

Use get_project_config and update_project_config for project-level settings.

Examples

Execute a tool (client-level)

use composio_sdk::models::tools::ToolExecuteParams;
use std::collections::HashMap;

let mut arguments = HashMap::new();
arguments.insert("owner".to_string(), serde_json::json!("acme"));
arguments.insert("repo".to_string(), serde_json::json!("demo"));
arguments.insert("title".to_string(), serde_json::json!("Issue from SDK"));

let response = client
    .execute_tool(ToolExecuteParams {
        slug: "GITHUB_CREATE_ISSUE".to_string(),
        arguments,
        user_id: Some("user_123".to_string()),
        ..Default::default()
    })
    .await?;

Create an MCP server

use composio_sdk::models::mcp::MCPCreateParams;

let mcp = client
    .create_mcp_server(MCPCreateParams {
        name: "my-mcp".to_string(),
        auth_config_ids: vec!["ac_123".to_string()],
        allowed_tools: None,
        no_auth_apps: None,
        toolkits: None,
        custom_tools: None,
        managed_auth_via_composio: Some(false),
    })
    .await?;

List connected accounts

use composio_sdk::models::connected_accounts::ConnectedAccountListParams;

let accounts = client
    .list_connected_accounts(ConnectedAccountListParams {
        user_ids: Some(vec!["user_123".to_string()]),
        ..Default::default()
    })
    .await?;

Upload a file (helper flow)

use composio_sdk::models::files::FileUploadable;
use std::path::Path;

let uploaded = FileUploadable::from_path(
    &client,
    Path::new("./invoice.pdf"),
    "GMAIL_SEND_EMAIL",
    "gmail",
)
.await?;

println!("s3 key: {}", uploaded.s3key);

Create a CLI session

let cli = client.create_cli_session().await?;
println!("session code: {}", cli.code);

Architecture

• src/client.rs: API methods and HTTP orchestration.
• src/models/: typed request/response models by domain.
• src/session.rs: Tool Router session abstraction.
• src/meta_tools/: Rust-native meta tool helpers.

Error Handling

Most APIs return Result<T, ComposioError>.

match client.create_cli_session().await {
    Ok(session) => println!("code={}", session.code),
    Err(err) => eprintln!("request failed: {err}"),
}

Contributing

1. Keep changes focused by domain.
2. Add/adjust serialization + deserialization tests for model changes.
3. Run:
   • cargo fmt --all
   • cargo test
   • cargo check
4. Keep parity work aligned with COMPOSIO_CLIENT_AUDIT_REPORT.md.

Roadmap

Major parity gaps have been closed (MCP, CLI, migration, project config, connected-account lifecycle, auth-config lifecycle, direct link endpoint, files list/upload-request, tool/trigger enums, toolkit retrieve version params).

Remaining work is mainly contract-shape refinement in partially covered domains tracked in COMPOSIO_CLIENT_AUDIT_REPORT.md.

License

Licensed under either:

• MIT
• Apache-2.0

at your option.