MCP API — Composio TypeScript SDK Reference Guide

Composio exposes tool sessions as Model Context Protocol (MCP) servers. This means any MCP-compatible client — Claude Desktop, Cursor, Windsurf, custom MCP clients, or any agent framework with MCP support — can connect directly to a Composio session and call tools without writing additional integration code. There are two ways to use MCP in Composio:

Session MCP (session.mcp): The MCP endpoint for a specific tool router session, scoped to one user. Created by composio.create().
Persistent MCP servers (composio.mcp): Named, shareable MCP server configurations that can generate per-user URLs. Managed via composio.mcp.create(), composio.mcp.list(), etc.

Session MCP

Every Session object returned by composio.create() includes a mcp property with the server details.

session.mcp

type

"http" | "sse"

Connection type. 'http' for Streamable HTTP (recommended), 'sse' for Server-Sent Events.

url

string

The MCP server URL for this session. Pass this to any MCP client to connect.

headers

Record<string, string> | undefined

Authentication headers to include with every MCP request. Pass these alongside url to your MCP client.

composio.mcp.create()

Create a persistent, named MCP server configuration that generates per-user URLs.

composio.mcp.create(
  name: string,
  config: MCPConfigCreationParams
): Promise<MCPConfigCreateResponse>

name

string

required

Unique name for this MCP server configuration.

config.toolkits

Array<string | { toolkit?: string; authConfigId?: string }>

required

Toolkits to expose via this MCP server. Pass toolkit slugs as strings, or objects with toolkit and/or authConfigId for more control.

config.allowedTools

string[]

Restrict the server to specific tool slugs. If omitted, all tools from the configured toolkits are available.

config.manuallyManageConnections

boolean

When false (default), Composio injects account management tools into the MCP server so agents can request and authenticate user accounts during a session. When true, you must manage connections manually before users connect.

MCPConfigCreateResponse

string

Unique identifier for the MCP server configuration.

name

string

Server name.

allowedTools

string[]

Tools available on this server.

authConfigIds

string[]

Auth config IDs associated with this server.

commands

object

Ready-to-paste client setup commands.

Show commands fields

claude

string

Claude Desktop configuration snippet.

cursor

string

Cursor IDE configuration snippet.

windsurf

string

Windsurf configuration snippet.

MCPUrl

string

Base MCP server URL (without user scoping).

generate

function

(userId: string) => Promise<MCPServerInstance> — generate a per-user URL for this server.

composio.mcp.generate()

Generate a per-user URL for an existing MCP server configuration.

composio.mcp.generate(
  userId: string,
  mcpConfigId: string,
  options?: MCPGetInstanceParams
): Promise<MCPServerInstance>

userId

string

required

External user identifier. The generated URL is scoped to this user.

mcpConfigId

string

required

MCP server configuration ID from composio.mcp.create().

options.manuallyManageConnections

boolean

Override the server-level connection management setting for this URL.

MCPServerInstance

string

MCP server configuration ID.

name

string

Server name.

type

"streamable_http"

Connection type.

url

string

Per-user MCP server URL. Pass this URL to an MCP client.

userId

string

The user this URL is scoped to.

allowedTools

string[]

Tools available via this URL.

authConfigs

string[]

Auth config IDs backing this server instance.

composio.mcp.list()

List MCP server configurations with optional filtering.

composio.mcp.list(options: MCPListParams): Promise<MCPListResponse>

options.page

number

Page number (1-based). Defaults to 1.

options.limit

number

Items per page. Defaults to 10.

options.toolkits

string[]

Filter by toolkit slugs.

options.authConfigs

string[]

Filter by auth config IDs.

options.name

string

Filter by server name (partial match).

composio.mcp.get()

Retrieve a specific MCP server configuration by ID.

composio.mcp.get(serverId: string): Promise<MCPItem>

composio.mcp.update()

Update an existing MCP server configuration.

composio.mcp.update(serverId: string, config: MCPUpdateParams): Promise<MCPItem>

config.name

string

New server name.

config.toolkits

array

Updated toolkit configuration. Replaces the entire toolkit list.

config.allowedTools

string[]

Updated tool allowlist.

config.manuallyManageConnections

boolean

Updated connection management setting.

composio.mcp.delete()

Delete an MCP server configuration permanently.

composio.mcp.delete(serverId: string): Promise<{ id: string; deleted: boolean }>

This operation is irreversible. All associated data and user connections to this MCP server will be permanently removed.

Examples

Session MCP with Claude Desktop
Persistent MCP server
MCP client in TypeScript
List and manage servers

import { Composio } from '@composio/core';

const composio = new Composio();

// Create a session for a user
const session = await composio.create('user_123', {
  toolkits: ['github', 'slack'],
  manageConnections: true,
});

// Pass these details to an MCP client
console.log('MCP URL:', session.mcp.url);
console.log('MCP headers:', session.mcp.headers);

// Example: configure Claude Desktop (claude_desktop_config.json)
const claudeConfig = {
  mcpServers: {
    composio: {
      url: session.mcp.url,
      headers: session.mcp.headers ?? {},
    },
  },
};
console.log('Claude Desktop config:', JSON.stringify(claudeConfig, null, 2));

import { Composio } from '@composio/core';

const composio = new Composio();

// Create a persistent MCP server configuration
const server = await composio.mcp.create('my-dev-tools', {
  toolkits: ['github', 'slack'],
  allowedTools: [
    'GITHUB_CREATE_ISSUE',
    'GITHUB_LIST_PULL_REQUESTS',
    'SLACK_SEND_MESSAGE',
  ],
  manuallyManageConnections: false,
});

console.log('MCP Server ID:', server.id);
console.log('Base MCP URL:', server.MCPUrl);
console.log('Claude setup command:', server.commands.claude);

// Generate a per-user URL
const instance = await server.generate('user_123');
console.log('User-scoped URL:', instance.url);

import { Composio } from '@composio/core';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const composio = new Composio();

const session = await composio.create('user_123', {
  toolkits: ['github'],
});

// Connect an MCP client to the session
const client = new Client({ name: 'my-app', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport(
  new URL(session.mcp.url),
  {
    requestInit: {
      headers: session.mcp.headers ?? {},
    },
  }
);

await client.connect(transport);

// List available tools
const { tools } = await client.listTools();
console.log('Available tools:', tools.map(t => t.name));

// Call a tool
const result = await client.callTool({
  name: 'GITHUB_LIST_PULL_REQUESTS',
  arguments: { owner: 'my-org', repo: 'my-repo' },
});
console.log('PRs:', result.content);

import { Composio } from '@composio/core';

const composio = new Composio();

// List all MCP server configurations
const { items, totalPages } = await composio.mcp.list({
  page: 1,
  limit: 10,
});

for (const server of items) {
  console.log(`${server.name} (${server.id})`);
  console.log(`  Tools: ${server.allowedTools.length}`);
  console.log(`  Instances: ${server.serverInstanceCount}`);
  console.log(`  Toolkits: ${server.toolkits.join(', ')}`);
}

// Update a server to add a new toolkit
await composio.mcp.update('mcp_12345', {
  toolkits: ['github', 'slack', 'jira'],
});

TypeScript SDK

Python SDK

REST API

MCP API — Composio TypeScript SDK Reference Guide

Session MCP

session.mcp

composio.mcp.create()

MCPConfigCreateResponse

composio.mcp.generate()

MCPServerInstance

composio.mcp.list()

composio.mcp.get()

composio.mcp.update()

composio.mcp.delete()

Examples

Build docs developers (and LLMs) love

TypeScript SDK

Python SDK

REST API

Documentation Index

​Session MCP

​session.mcp

​composio.mcp.create()

​MCPConfigCreateResponse

​composio.mcp.generate()

​MCPServerInstance

​composio.mcp.list()

​composio.mcp.get()

​composio.mcp.update()

​composio.mcp.delete()

​Examples

Build docs developers (and LLMs) love

Session MCP

session.mcp

composio.mcp.create()

MCPConfigCreateResponse

composio.mcp.generate()

MCPServerInstance

composio.mcp.list()

composio.mcp.get()

composio.mcp.update()

composio.mcp.delete()

Examples