Composio Tool Router
Relevant source files
The following files were used as context for generating this wiki page:
The Composio Tool Router is a core integration component that enables the Open Claude Cowork application to interface with over 500 external tools, including Gmail, Slack, GitHub, and Google Drive. It acts as a bridge between AI agents (Claude Agent SDK or Opencode SDK) and the Model Context Protocol (MCP) ecosystem, providing authenticated access to third-party services.
Sources: README.md:21-21, README.md:124-126
Architecture and Integration
The Composio Tool Router operates as an MCP server integration layer. During application startup, the backend server initializes a Composio session, which generates a unique MCP URL and associated security headers. These credentials are then used to configure the AI providers, allowing them to discover and invoke tools autonomously.
System Flow
The following diagram illustrates how the backend initializes the Composio session and propagates the configuration to the Opencode provider via a local JSON file.
The application uses the @composio/core package to manage these sessions and provides a dedicated COMPOSIO_API_KEY for authentication.
Sources: server/server.js:18-45, server/server.js:95-101, README.md:167-185
Backend Implementation
The backend logic for the Tool Router is centered in server/server.js. It manages user-specific sessions using a Map data structure to ensure that tool access is isolated per user.
Key Components
| Component | Description |
|---|---|
composioSessions | A Map storing session objects keyed by userId. |
initializeComposioSession() | Async function that creates the default session on startup. |
updateOpencodeConfig() | Writes the remote MCP URL and headers to server/opencode.json. |
mcpServers object | A configuration object passed to AI providers containing the HTTP URL and headers. |
Sources: server/server.js:21-55, server/server.js:92-105
Session Initialization Logic
async function initializeComposioSession() {
const defaultUserId = 'default-user';
try {
defaultComposioSession = await composio.create(defaultUserId);
composioSessions.set(defaultUserId, defaultComposioSession);
// Update opencode.json with the MCP config
updateOpencodeConfig(defaultComposioSession.mcp.url, defaultComposioSession.mcp.headers);
} catch (error) {
console.error('[COMPOSIO] Failed to pre-initialize session:', error.message);
}
}
Sources: server/server.js:24-38
Tool Execution and Streaming
When an agent invokes a tool, the request is routed through the provider to the Composio MCP endpoint. The results are then streamed back to the frontend using Server-Sent Events (SSE).
Execution Sequence
The sequence below shows the interaction between the User, the Backend Provider, and the Composio Router during a tool call.
Frontend Visualization
The frontend provides real-time tracking of tool calls through a dedicated sidebar and inline message components. The renderer.js script handles the tool_use and tool_result event types to update the UI.
UI Components for Tools
- Sidebar Progress: Displays a list of tool calls with statuses:
running,success, orerror. - Inline Tool Calls: Expanded views within the chat stream showing the JSON input and output of the tool.
- Todo List: Integration with the
TodoWritetool to track agent task progress in the sidebar.
Sources: renderer/renderer.js:1015-1080, renderer/index.html:195-215, renderer/renderer.js:1115-1150
Configuration and Setup
The Composio integration requires specific environment variables and setup steps managed by the setup.sh script.
Configuration Requirements
| Variable | Description |
|---|---|
COMPOSIO_API_KEY | Required for authenticating with the Composio platform. |
opencode.json | Auto-generated file containing the remote MCP configuration. |
The setup.sh script automates the retrieval of the API key by running the composio whoami command and updating the .env file.
Sources: setup.sh:66-83, README.md:187-198
The Composio Tool Router is essential for extending the capabilities of the Open Claude Cowork agents beyond simple chat, allowing them to perform complex, end-to-end automations across various workplace applications.