For most use cases, use a regular session instead. Sessions provide dynamic tool access and a much better MCP experience with context management handled by us.
Install the SDK
- Python
- TypeScript
uv add composio
pip install composio
npm install @composio/core
pnpm add @composio/core
yarn add @composio/core
bun add @composio/core
Create an MCP server
1
Initialize Composio
- Python
- TypeScript
from composio import Composio
composio = Composio(api_key="YOUR_API_KEY")
import { Composio } from '@composio/core';
const composio = new Composio({
apiKey: process.env.COMPOSIO_API_KEY
});
2
Create server configuration
Before you begin: Create an auth configuration for your toolkit.
- Python
- TypeScript
- API
server = composio.mcp.create(
name="my-gmail-server",
toolkits=[{
"toolkit": "gmail",
"auth_config": "ac_xyz123"
}],
allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
)
print(f"Server created: {server.id}")
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
const server = await composio.mcp.create("my-gmail-server", {
toolkits: [
{
authConfigId: "ac_xyz123",
toolkit: "gmail"
}
],
allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]
});
console.log(`Server created: ${server.id}`);
SERVER_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/mcp/servers/custom \
-H "x-api-key: $COMPOSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "my-gmail-server",
"toolkits": ["gmail"],
"auth_config_ids": ["ac_xyz123"],
"allowed_tools": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
"managed_auth_via_composio": true
}' | jq -r '.id')
echo "Server created: $SERVER_ID"
You can also create and manage MCP configs from the Composio dashboard.
3
Generate user URLs
Users must authenticate with the toolkits configured in your MCP server first. See authentication for details.
- Python
- TypeScript
- API
instance = composio.mcp.generate(user_id="user-123", mcp_config_id=server.id)
print(f"MCP Server URL: {instance['url']}")
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
const server = { id: 'my-gmail-server' };
const instance = await composio.mcp.generate("user-123", server.id);
console.log("MCP Server URL:", instance.url);
curl -s -X POST https://backend.composio.dev/api/v3.1/mcp/servers/generate \
-H "x-api-key: $COMPOSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"mcp_server_id": "'"$SERVER_ID"'", "user_ids": ["user-123"], "managed_auth_by_composio": true}' \
| jq -r '.user_ids_url[0]'
4
Use with AI providers
Pass an
x-api-key header when connecting to Composio MCP. This is required when require_mcp_api_key is enabled (default for newly created organizations).For consumer connections, use
https://connect.composio.dev/mcp, not this URL.COMPOSIO_MCP_URL to the URL returned by the generate step, and keep COMPOSIO_API_KEY on the server. Don’t construct the MCP URL from a server ID.- OpenAI
- Anthropic
- Mastra
- Python
- TypeScript
import os
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5.4",
tools=[{
"type": "mcp",
"server_label": "composio-server",
"server_url": os.environ["COMPOSIO_MCP_URL"],
"headers": {"x-api-key": os.environ["COMPOSIO_API_KEY"]},
"require_approval": "never",
}],
input="What are my latest emails?",
)
print(response.output_text)
import OpenAI from 'openai';
const mcpServerUrl = process.env.COMPOSIO_MCP_URL;
const apiKey = process.env.COMPOSIO_API_KEY;
if (!mcpServerUrl || !apiKey) throw new Error('Set COMPOSIO_MCP_URL and COMPOSIO_API_KEY');
const client = new OpenAI();
const response = await client.responses.create({
model: 'gpt-5.4',
tools: [{
type: 'mcp',
server_label: 'composio-server',
server_url: mcpServerUrl,
headers: { 'x-api-key': apiKey },
require_approval: 'never',
}],
input: 'What are my latest emails?',
});
console.log(response.output_text);
- Python
- TypeScript
Anthropic’s hosted MCP connector accepts a Bearer
authorization_token, not arbitrary headers. Its Python mcp_servers options cannot send the x-api-key required by Composio MCP servers. Use the Claude Agent SDK HTTP transport, which forwards headers, instead.The TypeScript Anthropic SDK has the same hosted-connector limitation:
mcp_servers accepts authorization_token, not headers. It cannot send the x-api-key required by Composio MCP servers. Use the Claude Agent SDK HTTP transport with the generated URL and headers instead.import { MCPClient } from '@mastra/mcp';
import { Agent } from '@mastra/core/agent';
const mcpServerUrl = process.env.COMPOSIO_MCP_URL;
const apiKey = process.env.COMPOSIO_API_KEY;
if (!mcpServerUrl || !apiKey) throw new Error('Set COMPOSIO_MCP_URL and COMPOSIO_API_KEY');
const client = new MCPClient({
id: 'mcp-client',
servers: {
composio: {
url: new URL(mcpServerUrl),
requestInit: { headers: { 'x-api-key': apiKey } },
},
},
});
try {
const agent = new Agent({
id: 'assistant',
name: 'Assistant',
instructions: 'You are a helpful assistant that can read and manage emails.',
model: 'openai/gpt-5.4',
tools: await client.listTools(),
});
const response = await agent.generate('What are my latest emails?');
console.log(response.text);
} finally {
await client.disconnect();
}
Server management
List servers
- Python
- TypeScript
- API
servers = composio.mcp.list(limit=10, page_no=1)
print(f"Found {len(servers['items'])} servers")
# Filter by toolkit
gmail_servers = composio.mcp.list(toolkits="gmail", limit=20, page_no=1)
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const servers = await composio.mcp.list({
toolkits: [],
authConfigs: [],
limit: 10,
page: 1
});
console.log(`Found ${servers.items.length} servers`);
// Filter by toolkit
const gmailServers = await composio.mcp.list({
toolkits: ["gmail"],
authConfigs: [],
limit: 20,
page: 1
});
curl -X GET "https://backend.composio.dev/api/v3.1/mcp/servers?limit=10&page_no=1" \
-H "x-api-key: $COMPOSIO_API_KEY"
# Filter by toolkit
curl -X GET "https://backend.composio.dev/api/v3.1/mcp/servers?toolkits=gmail&limit=20&page_no=1" \
-H "x-api-key: $COMPOSIO_API_KEY"
Get server details
- Python
- TypeScript
- API
server = composio.mcp.get("mcp_server_id")
print(f"Server: {server.name}")
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const server = await composio.mcp.get("mcp_server_id");
console.log(`Server: ${server.name}`);
curl -X GET https://backend.composio.dev/api/v3.1/mcp/mcp_server_id \
-H "x-api-key: $COMPOSIO_API_KEY"
Update a server
- Python
- TypeScript
- API
updated = composio.mcp.update(
server_id="mcp_server_id",
name="updated-name",
allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEARCH_EMAILS"]
)
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const updated = await composio.mcp.update("mcp_server_id", {
name: "updated-name",
allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEARCH_EMAILS"]
});
curl -X PATCH https://backend.composio.dev/api/v3.1/mcp/mcp_server_id \
-H "x-api-key: $COMPOSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "updated-name", "allowed_tools": ["GMAIL_FETCH_EMAILS", "GMAIL_SEARCH_EMAILS"]}'
Delete a server
- Python
- TypeScript
- API
result = composio.mcp.delete("mcp_server_id")
if result['deleted']:
print("Server deleted")
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'your_api_key' });
const result = await composio.mcp.delete("mcp_server_id");
if (result.deleted) {
console.log("Server deleted");
}
curl -X DELETE https://backend.composio.dev/api/v3.1/mcp/mcp_server_id \
-H "x-api-key: $COMPOSIO_API_KEY"
Next
Providers
Use with Anthropic, OpenAI, and other frameworks