Skip to main content
The Claude Agent SDK provider enables seamless integration of Composio tools with Claude Code Agents SDK, allowing you to use any Composio-supported tool (Gmail, Slack, GitHub, etc.) within your Claude agents.

​
Installation

npm install @composio/claude-agent-sdk @composio/core @anthropic-ai/claude-agent-sdk

​
Prerequisites

1

Install Claude Code CLI

The Claude Agent SDK requires Claude Code to be installed:
curl -fsSL https://claude.ai/install.sh | bash
2

Set up API keys

Configure your environment variables:
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export COMPOSIO_API_KEY="your-composio-api-key"

​
Quick Start

import { Composio } from '@composio/core';
import { ClaudeAgentSDKProvider } from '@composio/claude-agent-sdk';
import { query, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';

// Initialize Composio with Claude Agent SDK provider
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY,
  provider: new ClaudeAgentSDKProvider(),
});

// Create a tool router session
const session = await composio.create('external_user_id');

// Get tools from the session
const tools = await session.tools();

// Create MCP server using Claude Agent SDK's createSdkMcpServer
const customServer = createSdkMcpServer({
  name: 'composio',
  version: '1.0.0',
  tools: tools,
});

// Use with Claude Agent SDK
for await (const content of query({
  prompt: 'Fetch my last email from gmail',
  options: {
    mcpServers: { composio: customServer },
    permissionMode: 'bypassPermissions',
  },
})) {
  if (content.type === 'assistant') {
    console.log('Claude:', content.message);
  }
}

console.log('✅ Received response from Claude');

​
API Reference

​
ClaudeAgentSDKProvider

The main provider class for integrating Composio tools with Claude Code Agents.
​
options
ClaudeAgentSDKProviderOptions
Configuration options for the provider

​
Methods

​
wrapTool()

Wraps a single Composio tool as a Claude Agent SDK MCP tool. 
wrapTool(
  composioTool: Tool,
  executeTool: ExecuteToolFn
): ClaudeAgentTool
​
composioTool
Tool
required
The Composio tool to wrap
​
executeTool
ExecuteToolFn
required
Function to execute the tool

​
wrapTools()

Wraps multiple Composio tools as Claude Agent SDK MCP tools. 
wrapTools(
  tools: Tool[],
  executeTool: ExecuteToolFn
): ClaudeAgentToolCollection
​
tools
Tool[]
required
Array of Composio tools to wrap
​
executeTool
ExecuteToolFn
required
Function to execute the tools

​
Examples

​
Using Multiple Tools

import { Composio } from '@composio/core';
import { ClaudeAgentSDKProvider } from '@composio/claude-agent-sdk';
import { query, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';

const composio = new Composio({
  provider: new ClaudeAgentSDKProvider(),
});

// Get multiple tools
const tools = await composio.tools.get('default', [
  'GMAIL_SEND_EMAIL',
  'GMAIL_LIST_EMAILS',
  'SLACK_POST_MESSAGE',
]);

// Wrap tools and create MCP server
const mcpServer = createSdkMcpServer({
  name: 'composio',
  version: '1.0.0',
  tools,
});

// Execute query
for await (const message of query({
  prompt: 'Check my latest emails and post a summary to #general on Slack',
  options: {
    mcpServers: { composio: mcpServer },
  },
})) {
  console.log(message);
}

​
Custom Server Configuration

const provider = new ClaudeAgentSDKProvider({
  serverName: 'my-composio-tools',
  serverVersion: '2.0.0',
});

const composio = new Composio({
  provider,
});

​
With Tool Router Session

// Create a session for a specific user
const session = await composio.toolRouter.createSession({
  userId: '[email protected]',
});

// Get tools from the session (automatically handles authentication)
const tools = await session.tools(['GITHUB_CREATE_ISSUE', 'GITHUB_LIST_REPOS']);

// Create MCP server with session tools
const mcpServer = createSdkMcpServer({
  name: 'github-tools',
  version: '1.0.0',
  tools,
});

for await (const content of query({
  prompt: 'Create an issue in my top starred repo',
  options: {
    mcpServers: { github: mcpServer },
  },
})) {
  if (content.type === 'assistant') {
    console.log(content.message);
  }
}

​
How It Works

The Claude Agent SDK uses MCP (Model Context Protocol) servers to provide tools to Claude agents. This provider:
  1. Converts Composio tool definitions to MCP tool format
  2. Creates an in-process MCP server using createSdkMcpServer()
  3. Handles tool execution by routing calls through Composio’s execution layer
  4. Manages authentication and connected accounts automatically
The Claude Agent SDK provider is built on top of Composio’s agentic provider base, which means it automatically handles tool wrapping and execution delegation.

​
Permission Modes

The Claude Agent SDK supports different permission modes: 
for await (const content of query({
  prompt: 'Send an email',
  options: {
    mcpServers: { composio: mcpServer },
    permissionMode: 'ask', // 'ask' | 'bypassPermissions' | 'deny'
  },
})) {
  // Handle response
}
  • ask: Ask for permission before executing tools (default)
  • bypassPermissions: Skip permission prompts (useful for automation)
  • deny: Deny all tool executions

​
Type Exports

import type {
  ClaudeAgentTool,
  ClaudeAgentToolCollection,
  ClaudeAgentOptions,
} from '@composio/claude-agent-sdk';
​
ClaudeAgentTool
type
Type for a single Claude Agent SDK MCP tool definition
​
ClaudeAgentToolCollection
type
Type for a collection of Claude Agent SDK MCP tools
​
ClaudeAgentOptions
type
Options type from @anthropic-ai/claude-agent-sdk

Claude Agent SDK Docs

Official Claude Agent SDK documentation

MCP Overview

Learn about Model Context Protocol

Tool Router

Advanced tool routing and session management

Anthropic Provider

Standard Anthropic provider for Claude API

Build docs developers (and LLMs) love

Get started for freeTalk to us