SIGN UPLOG IN
X (Twitter)LinkedInGitHubDiscordYouTube

How to integrate Plain MCP with OpenAI Agents SDK

Connect OpenAI Agents SDK to Plain MCP. Add a customer to the enterprise group, fetch company details for acme corp, and more using natural language, with authentication handled for you.

Get started for freeGet a demo
Plain logoPlain
Api Key

Plain is a collaborative support platform for B2B teams, focused on consolidating conversations and boosting efficiency with AI. Enjoy streamlined, modern workflows to assist customers across channels from one place.

119 Tools11 Triggers

Introduction

This guide walks you through connecting Plain to the OpenAI Agents SDK using the Composio tool router. By the end, you'll have a working Plain agent that can add a customer to the enterprise group, fetch company details for acme corp, list all issues linked to this customer through natural language commands.

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

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

Also integrate Plain with

Claude CodeClaude CoworkClaude Agent SDKCodexOpenClawHermesAtomic AgentGoogle ADKLangChainVercel AI SDKMastra AILlamaIndexCrewAIPydantic AIAutoGen

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 Plain
  • Configure an AI agent that can use Plain as a tool
  • Run a live chat session where you can ask the agent to perform Plain 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 Plain MCP server, and what's possible with it?

The Plain MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Plain account. It provides structured and secure access to your B2B support workspace, so your agent can perform actions like managing customers, creating support threads, fetching company details, handling issues, and organizing customer groups on your behalf.

  • Customer management and onboarding: Automatically create new customer records, fetch customer information by email or ID, and add customers to specific support groups for better organization.
  • Support thread creation: Let your agent create new support threads tied to customers, making it easy to kick off or escalate conversations without manual intervention.
  • Issue tracking and retrieval: Fetch all external issue links associated with a customer, helping your team stay on top of ongoing problems and resolutions.
  • Company and tier information access: Retrieve detailed company profiles and tier metadata, including contract value, owner details, and more, to personalize support interactions.
  • User and customer cleanup: Safely delete customers or users from the system when offboarding or data hygiene is needed, all through agent-driven actions.

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 Plain 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 Plain.
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 Plain
const session = await composio.create(userId as string, {
  toolkits: ['plain'],
});
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 plain.
  • The router checks the user's Plain connection and prepares the MCP endpoint.
  • The returned session.mcp.url is the MCP URL that your agent will use to access Plain.
  • This approach keeps things lightweight and lets the agent request Plain 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 Plain. Help users perform Plain 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 Plain 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 Plain 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 Plain.
  • 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 Plain 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: ['plain'],
  });
  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 Plain. Help users perform Plain 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 Plain MCP with OpenAI Agents SDK to build a functional AI agent that can interact with Plain.

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 & TRIGGERS

Supported Tools and Triggers

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

Add Customer To Group

Add a customer to up to 25 customer groups.

Add Customer To Tenants

Idempotently add a customer to one or more tenants.

Add Generated Reply

Add a suggested reply for teammate review without sending it to the customer.

Add Labels To Thread

Add one or more labels to a thread by label-type ID.

Add Members to Tier

Add or move up to 25 tenants or companies into one tier.

Archive Label Type

Archive a label type while preserving labels already on threads.

Bulk Delete Thread Fields

Sequentially delete thread fields, returning each non-atomic item result.

Bulk Set Thread Fields

Create or replace multiple typed thread-field values.

Change Thread Assignment

Irreversibly assign, unassign, add, or remove thread assignees.

Create Attachment Download URL

Create a sensitive three-minute URL and return its virus-scan result.

Create Attachment Upload Form

Create a sensitive, two-hour presigned upload capability; no file is uploaded.

Create Autoresponder

Create an autoresponder that automatically sends outbound customer replies.

Create Customer Group

Creates a new customer group in Plain for organizing and segmenting customers.

Create Email/Slack Discussion

Immediately and irreversibly start an external EMAIL or SLACK discussion.

Create Customer Or Thread Event

Create a custom customer-wide or single-thread timeline event.

Create Label Type

Create a label type that can be applied to threads.

Create Note

Create an internal note on an existing customer thread.

Create Tier SLA

Create one legacy tier SLA; next-response requires a first-response SLA on the tier.

Create SLA Policy

Create a named SLA policy with zero or more unique target types.

Create Snippet

Create a reusable plain-text and optional Markdown reply snippet.

Create Task

Create a task, optionally linked to one parent and one assignee.

Create Thread

Create a thread after obtaining a valid customer identifier.

Create Thread Field Schema

Create a custom thread-field schema.

Create Tier

Create a support tier, optionally assigning tenant or company members.

Delete Autoresponder

Permanently delete a native autoresponder.

Delete Customer

Permanently and irreversibly deletes a Plain customer by ID, including all associated threads, timeline entries, and other customer data.

Delete Customer Group

Permanently delete an empty customer group after confirmation.

Delete Note

Soft-delete an internal note.

Delete Tier SLA

Delete a legacy SLA from a tier.

Delete SLA Policy

Delete an SLA policy, its targets, and their trackers.

Delete Snippet

Soft-delete a snippet while preserving historical references.

Delete Task

Soft-delete a task and remove its thread links.

Delete Tenant

Delete a tenant, unlink its customers, and remove its field values.

Delete Tenant Field Value

Clear one tenant field value without deleting its schema.

Delete Tenant Field Schema

Permanently delete a tenant-field schema and all values stored against it.

Delete Thread

Permanently delete a thread and all associated data.

Delete Thread Field Schema

Delete a schema and all values stored against it.

Delete Tier

Permanently delete a tier and all of its memberships.

Delete User

Permanently removes a Plain workspace user by ID.

Escalate Thread Or Select Path

Advance a thread's escalation or attach/detach its escalation path.

Fetch Company

Tool to fetch company details by ID.

Fetch Issues

Fetches external issue tracker links (Jira, Linear, GitHub, etc.

Fetch Tier

Fetch a tier by ID.

Get Autoresponder

Fetch one native Plain autoresponder through the machine-user-safe list query.

Get Customer By Email

Fetch customer details by email address.

Get Customer By External ID

Fetch a customer by the exact stable external ID from your own system.

Get Customer By ID

Tool to retrieve details of a specific customer by their unique ID.

Get Customer Group

Fetch one customer group by its Plain ID.

Get Customers

Tool to fetch a list of customers.

Get Email/Slack Discussion

Fetch metadata for one EMAIL or SLACK side-conversation by ID.

Get Knowledge Gap

Fetch one AI-detected knowledge gap and its linked task and signals.

Get Label Type

Fetch one label type by Plain ID or external ID.

Get SLA Policy

Fetch one SLA policy by its Plain ID.

Get Snippet

Fetch one snippet by ID, including a soft-deleted snippet.

Get Task by ID or Ref

Fetch one task by either its Plain ID or human-readable T-123 ref.

Get Tenant

Fetch one tenant by its Plain ID, including current custom field values.

Get Thread By ID

Fetches a thread by ID, including customer info, status, priority, labels, and assignments.

Get Thread By Reference

Fetch a thread by ref or by its customer-scoped external ID.

Get User By ID

Fetch workspace user/team member by ID.

Import Thread

Import one historical thread without triggering SLAs or autoresponders.

Import Thread Messages

Import up to 25 historical messages and return one result per input message.

List AI Feedback

List feedback submitted on Plain AI features, optionally filtered by feature, sentiment, or time.

List Autoresponders

List native Plain autoresponders in priority order.

List Customer Groups

List one paginated page of customer groups with optional external-ID filtering.

List Deleted Threads

List deletion-audit records for threads.

List Email/Slack Discussions

List only EMAIL and SLACK side-conversations with filters and pagination.

List Generated Replies

List current suggested replies for a thread's most recent inbound message.

List Knowledge Gaps

List AI-detected knowledge gaps with status filters and useful sort orders.

List Label Types

List active and/or archived label types.

List SLA Policies

List named SLA policies, optionally filtering by name or target type.

List Snippets

List the workspace snippet library with cursor pagination.

List Tasks

List workspace tasks with pagination, filtering, and sorting.

List Tenant Field Schemas

List tenant-field schemas before reading or writing custom values.

List Tenants

List tenants with current filters and cursor pagination.

List Thread Field Schemas

List the workspace's custom thread-field schemas.

List Threads By External ID

List a page of threads with an external ID across all customers.

List Threads With Rich Filters

List threads with the provider's complete public filter and sort surface.

List Tiers

List tiers with cursor pagination.

Mark Customer As Spam

Idempotently hide a customer's threads as spam and exclude them from metrics.

List Threads

Retrieve up to 50 threads from one page, optionally filtered by status.

Remove Customer From Group

Removes a customer from one or more customer groups in Plain.

Remove Customer From Tenants

Idempotently remove a customer from one or more tenants.

Remove Labels From Thread

Remove one or more concrete labels from a thread.

Remove Members from Tier

Remove up to 25 tenants or companies from their current tiers.

Reorder Autoresponders

Reorder native autoresponders in one call.

Reorder Thread Field Schemas

Reorder one or more thread-field schemas.

Reply To Email

Immediately and irreversibly send an external reply to an inbound email.

Run GraphQL Query

Execute an arbitrary GraphQL document against Plain without a safety gate.

Search Customers

Search customer profile fields or timeline text using explicit OR conditions.

Search Tenants

Search tenants by name, domain, or exact external ID.

Search Threads

Search thread titles, messages, and customer names or emails.

Send Email/Slack Discussion Message

Immediately and irreversibly deliver a message in an existing discussion.

Send Message

Immediately and irreversibly deliver a message through an existing thread.

Send New Email

Immediately and irreversibly send an external email to a customer.

Set Customer Tenants

Replace a customer's complete tenant membership set in one call.

Transition Thread Status

Move a thread to Todo, Snoozed, or Done.

Unarchive Label Type

Restore an archived label type for use on new threads.

Unmark Customer As Spam

Idempotently clear a customer's spam flag and restore inbox visibility.

Update Autoresponder

Update an autoresponder that automatically sends outbound customer replies.

Update Company

Upserts (creates or updates) a company in Plain.

Update Company Tier

Assign one company to a tier or clear its tier membership.

Update Generated Reply

Record teammate feedback on a generated reply.

Update Label Type

Update mutable label-type properties using field wrappers.

Update Note

Replace an internal note's content and optional attachment list.

Update Tier SLA

Update a legacy tier SLA without changing its SLA type.

Update SLA Policy

Replace an SLA policy's targets; omitted target types and their trackers are deleted.

Update Snippet

Update selected snippet fields using Plain's field-level wrappers.

Update Task

Update selected fields on an existing task.

Update Tenant Tier

Assign one tenant to a tier or clear its tier membership.

Update Thread Title

Tool to update a thread's title.

Update Thread Attributes

Change one thread priority, customer, external ID, tenant, or tier attribute.

Update Thread Field Schema

Update mutable properties of a thread-field schema.

Apply or Clear Thread SLA Policy

Apply an SLA policy, or clear it so the thread falls back to its tier's SLAs.

Update Tier

Update selected fields on an existing support tier.

Upsert Customer

Tool to upsert (create or update) a customer.

Upsert Customer Group

Idempotently create or update a customer group using machine-user-safe calls.

Upsert Tenant

Create or update a tenant while synchronizing its stable external ID.

Upsert Tenant Field

Set one typed custom field value for a tenant.

Upsert Tenant Field Schemas

Create or update tenant-field schemas keyed by source and external field ID.

FRAMEWORKS

How to build Plain MCP Agent with another framework

Claude Code logo

Claude Code

Use Plain MCP with Claude Code

Claude Cowork logo

Claude Cowork

Use Plain MCP with Claude Cowork

Claude Agent SDK logo

Claude Agent SDK

Use Plain MCP with Claude Agent SDK

Codex logo

Codex

Use Plain MCP with Codex

OpenClaw logo

OpenClaw

Use Plain MCP with OpenClaw

Hermes logo

Hermes

Use Plain MCP with Hermes

Atomic Agent logo

Atomic Agent

Use Plain MCP with Atomic Agent

Google ADK logo

Google ADK

Use Plain MCP with Google ADK

LangChain logo

LangChain

Use Plain MCP with LangChain

Vercel AI SDK logo

Vercel AI SDK

Use Plain MCP with Vercel AI SDK

Mastra AI logo

Mastra AI

Use Plain MCP with Mastra AI

LlamaIndex logo

LlamaIndex

Use Plain MCP with LlamaIndex

CrewAI logo

CrewAI

Use Plain MCP with CrewAI

Pydantic AI logo

Pydantic AI

Use Plain MCP with Pydantic AI

AutoGen logo

AutoGen

Use Plain MCP with AutoGen

FAQ

Frequently asked questions

With a standalone Plain MCP server, the agents and LLMs can only access a fixed set of Plain tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Plain 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 Plain tools.

Yes, absolutely. You can configure which Plain 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 Plain data and credentials are handled as safely as possible.

Start with Plain.It takes 30 seconds.

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

Start building