How to integrate Chatwork MCP with OpenAI Agents SDK

This guide walks you through connecting Chatwork to the OpenAI Agents SDK using the Composio tool router. By the end, you'll have a working Chatwork agent that can list all unread messages across rooms, upload meeting notes file to project room, get all members of marketing chat through natural language commands. This guide will help you understand how to give your OpenAI Agents SDK agent real control over a Chatwork account through Composio's Chatwork MCP server. Before we dive in, let's take a quick look at the key ideas and tools involved.

Chatwork logoChatwork
Api Key

Chatwork is a team communication platform with group chats, file sharing, and task management. It helps businesses boost collaboration and streamline productivity.

30 Tools

Introduction

This guide walks you through connecting Chatwork to the OpenAI Agents SDK using the Composio tool router. By the end, you'll have a working Chatwork agent that can list all unread messages across rooms, upload meeting notes file to project room, get all members of marketing chat through natural language commands.

This guide will help you understand how to give your OpenAI Agents SDK agent real control over a Chatwork account through Composio's Chatwork MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

Also integrate Chatwork with

TL;DR

Here's what you'll learn:
  • Get and set up your OpenAI and Composio API keys
  • Install the necessary dependencies
  • Initialize Composio and create a Tool Router session for Chatwork
  • Configure an AI agent that can use Chatwork as a tool
  • Run a live chat session where you can ask the agent to perform Chatwork operations

What is OpenAI Agents SDK?

The OpenAI Agents SDK is a lightweight framework for building AI agents that can use tools and maintain conversation state. It provides a simple interface for creating agents with hosted MCP tool support.

Key features include:

  • Hosted MCP Tools: Connect to external services through hosted MCP endpoints
  • SQLite Sessions: Persist conversation history across interactions
  • Simple API: Clean interface with Agent, Runner, and tool configuration
  • Streaming Support: Real-time response streaming for interactive applications

What is the Chatwork MCP server, and what's possible with it?

The Chatwork MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Chatwork account. It provides structured and secure access to your chats, contacts, files, and rooms, so your agent can perform actions like sending messages, managing tasks, retrieving files, and organizing team communications on your behalf.

  • Room and member management: Easily fetch all chat rooms, list members in any room, and keep your workspace organized by letting your agent handle the heavy lifting.
  • Smart message retrieval and deletion: Have your agent pull recent messages from any chat, search for important info, or even delete specific messages when needed.
  • File sharing and retrieval: Seamlessly upload files to any Chatwork room or retrieve details and download links for files already shared, making document collaboration a breeze.
  • Contact and status insights: Instantly get a list of all your Chatwork contacts or check your current unread messages and task status without switching tabs.
  • Automated task and notification workflows: Let your agent monitor unread messages, mentions, and tasks, helping you stay on top of communication and never miss an important update.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step09 STEPS
1

Prerequisites

Before starting, make sure you have:
  • Composio API Key and OpenAI API Key
  • Primary know-how of OpenAI Agents SDK
  • A live Chatwork project
  • Some knowledge of Python or Typescript
2

Getting API Keys for OpenAI and Composio

OpenAI API Key
  • Go to the OpenAI dashboard and create an API key. You'll need credits to use the models, or you can connect to another model provider.
  • Keep the API key safe.
Composio API Key
3

Install dependencies

npm install @composio/openai-agents @openai/agents dotenv

Install the Composio SDK and the OpenAI Agents SDK.

4

Set up environment variables

bash
OPENAI_API_KEY=sk-...your-api-key
COMPOSIO_API_KEY=your-api-key
USER_ID=composio_user@gmail.com

Create a .env file and add your OpenAI and Composio API keys.

5

Import dependencies

import 'dotenv/config';
import { Composio } from '@composio/core';
import { OpenAIAgentsProvider } from '@composio/openai-agents';
import { Agent, hostedMcpTool, run, OpenAIConversationsSession } from '@openai/agents';
import * as readline from 'readline';
What's happening:
  • You're importing all necessary libraries.
  • The Composio and OpenAIAgentsProvider classes are imported to connect your OpenAI agent to Composio tools like Chatwork.
6

Set up the Composio instance

dotenv.config();

const composioApiKey = process.env.COMPOSIO_API_KEY;
const userId = process.env.USER_ID;

if (!composioApiKey) {
  throw new Error('COMPOSIO_API_KEY is not set. Create a .env file with COMPOSIO_API_KEY=your_key');
}
if (!userId) {
  throw new Error('USER_ID is not set');
}

// Initialize Composio
const composio = new Composio({
  apiKey: composioApiKey,
  provider: new OpenAIAgentsProvider(),
});
What's happening:
  • dotenv.config() loads your .env file so COMPOSIO_API_KEY and USER_ID are available as environment variables.
  • Creating a Composio instance using the API Key and OpenAIAgentsProvider class.
7

Create a Tool Router session

// Create Tool Router session for Chatwork
const session = await composio.create(userId as string, {
  toolkits: ['chatwork'],
});
const mcpUrl = session.mcp.url;

What is happening:

  • You give the Tool Router the user id and the toolkits you want available. Here, it is only chatwork.
  • The router checks the user's Chatwork connection and prepares the MCP endpoint.
  • The returned session.mcp.url is the MCP URL that your agent will use to access Chatwork.
  • This approach keeps things lightweight and lets the agent request Chatwork tools only when needed during the conversation.
8

Configure the agent

// Configure agent with MCP tool
const agent = new Agent({
  name: 'Assistant',
  model: 'gpt-5',
  instructions:
    'You are a helpful assistant that can access Chatwork. Help users perform Chatwork operations through natural language.',
  tools: [
    hostedMcpTool({
      serverLabel: 'tool_router',
      serverUrl: mcpUrl,
      headers: { 'x-api-key': composioApiKey },
      requireApproval: 'never',
    }),
  ],
});
What's happening:
  • We're creating an Agent instance with a name, model (gpt-5), and clear instructions about its purpose.
  • The agent's instructions tell it that it can access Chatwork and help with queries, inserts, updates, authentication, and fetching database information.
  • The tools array includes a hostedMcpTool that connects to the MCP server URL we created earlier.
  • The headers object includes the Composio API key for secure authentication with the MCP server.
  • requireApproval: 'never' means the agent can execute Chatwork operations without asking for permission each time, making interactions smoother.
9

Start chat loop and handle conversation

// Keep conversation state across turns
const conversationSession = new OpenAIConversationsSession();

// Simple CLI
const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  prompt: 'You: ',
});

console.log('\nComposio Tool Router session created.');
console.log('\nChat started. Type your requests below.');
console.log("Commands: 'exit', 'quit', or 'q' to end\n");

try {
  const first = await run(agent, 'What can you help me with?', { session: conversationSession });
  console.log(`Assistant: ${first.finalOutput}\n`);
} catch (e) {
  console.error('Error:', e instanceof Error ? e.message : e, '\n');
}

rl.prompt();

rl.on('line', async (userInput) => {
  const text = userInput.trim();

  if (['exit', 'quit', 'q'].includes(text.toLowerCase())) {
    console.log('Goodbye!');
    rl.close();
    process.exit(0);
  }

  if (!text) {
    rl.prompt();
    return;
  }

  try {
    const result = await run(agent, text, { session: conversationSession });
    console.log(`\nAssistant: ${result.finalOutput}\n`);
  } catch (e) {
    console.error('Error:', e instanceof Error ? e.message : e, '\n');
  }

  rl.prompt();
});

rl.on('close', () => {
  console.log('\n👋 Session ended.');
  process.exit(0);
});
What's happening:
  • The program prints a session URL that you visit to authorize Chatwork.
  • After authorization, the chat begins.
  • Each message you type is processed by the agent using run().
  • The responses are printed to the console.
  • Typing exit, quit, or q cleanly ends the chat.

Complete Code

Here's the complete code to get you started with Chatwork and OpenAI Agents SDK:

import 'dotenv/config';
import { Composio } from '@composio/core';
import { OpenAIAgentsProvider } from '@composio/openai-agents';
import { Agent, hostedMcpTool, run, OpenAIConversationsSession } from '@openai/agents';
import * as readline from 'readline';

const composioApiKey = process.env.COMPOSIO_API_KEY;
const userId = process.env.USER_ID;

if (!composioApiKey) {
  throw new Error('COMPOSIO_API_KEY is not set. Create a .env file with COMPOSIO_API_KEY=your_key');
}
if (!userId) {
  throw new Error('USER_ID is not set');
}

// Initialize Composio
const composio = new Composio({
  apiKey: composioApiKey,
  provider: new OpenAIAgentsProvider(),
});

async function main() {
  // Create Tool Router session
  const session = await composio.create(userId as string, {
    toolkits: ['chatwork'],
  });
  const mcpUrl = session.mcp.url;

  // Configure agent with MCP tool
  const agent = new Agent({
    name: 'Assistant',
    model: 'gpt-5',
    instructions:
      'You are a helpful assistant that can access Chatwork. Help users perform Chatwork operations through natural language.',
    tools: [
      hostedMcpTool({
        serverLabel: 'tool_router',
        serverUrl: mcpUrl,
        headers: { 'x-api-key': composioApiKey },
        requireApproval: 'never',
      }),
    ],
  });

  // Keep conversation state across turns
  const conversationSession = new OpenAIConversationsSession();

  // Simple CLI
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    prompt: 'You: ',
  });

  console.log('\nComposio Tool Router session created.');
  console.log('\nChat started. Type your requests below.');
  console.log("Commands: 'exit', 'quit', or 'q' to end\n");

  try {
    const first = await run(agent, 'What can you help me with?', { session: conversationSession });
    console.log(`Assistant: ${first.finalOutput}\n`);
  } catch (e) {
    console.error('Error:', e instanceof Error ? e.message : e, '\n');
  }

  rl.prompt();

  rl.on('line', async (userInput) => {
    const text = userInput.trim();

    if (['exit', 'quit', 'q'].includes(text.toLowerCase())) {
      console.log('Goodbye!');
      rl.close();
      process.exit(0);
    }

    if (!text) {
      rl.prompt();
      return;
    }

    try {
      const result = await run(agent, text, { session: conversationSession });
      console.log(`\nAssistant: ${result.finalOutput}\n`);
    } catch (e) {
      console.error('Error:', e instanceof Error ? e.message : e, '\n');
    }

    rl.prompt();
  });

  rl.on('close', () => {
    console.log('\nSession ended.');
    process.exit(0);
  });
}

main().catch((err) => {
  console.error('Fatal error:', err);
  process.exit(1);
});

Conclusion

This was a starter code for integrating Chatwork MCP with OpenAI Agents SDK to build a functional AI agent that can interact with Chatwork.

Key features:

  • Hosted MCP tool integration through Composio's Tool Router
  • SQLite session persistence for conversation history
  • Simple async chat loop for interactive testing
You can extend this by adding more toolkits, implementing custom business logic, or building a web interface around the agent.
TOOLS

Supported Tools

Every Chatwork action and event your agent gets out of the box.

Create Chatwork Room

Tool to create a new group chat room in Chatwork.

Create Room Invitation Link

Tool to create an invitation link for a Chatwork room.

Create Task in Chatwork Room

Tool to create a new task in a Chatwork room.

Delete Message

This tool allows you to delete a specific message from a Chatwork room by calling the DELETE endpoint at https://api.

Delete or Leave Chatwork Room

Tool to leave or delete a Chatwork room.

Delete Room Link

Delete the invitation link for a Chatwork room.

Get Chatwork Contacts

This tool retrieves a list of all contacts from Chatwork.

Get Chatwork File Information

Tool to get information about a specific file in a chat room.

Get Incoming Contact Requests

Tool to retrieve pending contact approval requests received by the authenticated user.

Get My Chatwork Profile

Tool to retrieve the authenticated user's profile information including account details, organization, contact information, and avatar URL.

Get Message

Tool to retrieve information about a specific message in a Chatwork room.

Get My Chatwork Status

This tool retrieves the current status of the authenticated user, including unread message counts and task status.

Get My Chatwork Tasks

Tool to retrieve the authenticated user's task list from Chatwork (up to 100 items).

Get Chatwork Room

Retrieves detailed information about a specific Chatwork room using the API endpoint GET /rooms/{room_id}.

Get Room Files

Tool to get list of files in a chat room (up to 100 files).

Get Room Invitation Link

Retrieves the invitation link for a specified Chatwork room using the API endpoint GET /rooms/{room_id}/link.

Get Room Members

Retrieves a complete list of all members in a specified Chatwork room using the API endpoint GET /rooms/{room_id}/members.

Get Room Messages V2

Tool to retrieve messages from a Chatwork room (up to 100 messages).

Get Chatwork Rooms

Tool to retrieve a list of all chat rooms the authenticated user belongs to.

Get Room Tasks

Retrieves a list of tasks from a Chatwork room.

Get Task

Retrieves detailed information about a specific task in a Chatwork room using the API endpoint GET /rooms/{room_id}/tasks/{task_id}.

Mark Messages as Read

Tool to mark messages as read in a Chatwork room.

Mark Messages as Unread

Tool to mark messages as unread in a Chatwork room.

Post Message

Tool to post a new message to a Chatwork room.

Update Message

Tool to update an existing message in a Chatwork room.

Update Chatwork Room

Tool to update chat room information (name, icon, description).

Update Room Invitation Link

Tool to update the invitation link settings for a Chatwork room.

Update Room Members

Updates the complete member list of a Chatwork room with bulk assignment of member roles (admin, member, readonly).

Update Task Status

Tool to update the completion status of a task in a Chatwork room.

Upload File to Chatwork Room

This tool allows users to upload files to a specific Chatwork room.

FAQ

Frequently asked questions

With a standalone Chatwork MCP server, the agents and LLMs can only access a fixed set of Chatwork tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Chatwork and many other apps based on the task at hand, all through a single MCP endpoint.

Yes, you can. OpenAI Agents SDK fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Chatwork tools.

Yes, absolutely. You can configure which Chatwork scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Chatwork data and credentials are handled as safely as possible.

Start with Chatwork.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Chatwork tool your agent needs.Free to start.

Start building