> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Toolkit MCP

> Create MCP servers for specific toolkits

> [!NOTE]
>
> For most use cases, use a regular [session](https://composio-preview.mintlify.site/docs/configuring-sessions.md) instead. Sessions provide dynamic tool access and a much better MCP experience with context management handled by us.

## Install the SDK

> [tab] Python
>
> ```bash uv theme={null}
> uv add composio
> ```
>
> ```bash pip theme={null}
> pip install composio
> ```

> [tab] TypeScript
>
> ```bash npm theme={null}
> npm install @composio/core
> ```
>
> ```bash pnpm theme={null}
> pnpm add @composio/core
> ```
>
> ```bash yarn theme={null}
> yarn add @composio/core
> ```
>
> ```bash bun theme={null}
> bun add @composio/core
> ```

## Create an MCP server

**1. Initialize Composio**

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio(api_key="YOUR_API_KEY")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio({
>   apiKey: process.env.COMPOSIO_API_KEY
> });
> ```

**2. Create server configuration**

> [!WARNING]
>
> **Before you begin:** [Create an auth configuration](https://composio-preview.mintlify.site/docs/auth-configuration/custom-auth-configs.md) for your toolkit.

> [tab] Python
>
> ```python theme={null}
> 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}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> 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}`);
> ```

> [tab] API
>
> ```bash theme={null}
> 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"
> ```

> [!NOTE]
>
> You can also create and manage MCP configs from the [Composio dashboard](https://dashboard.composio.dev/~/org/connect/clients?utm_source=docs\&utm_medium=content\&utm_campaign=docs-single-toolkit-mcp).

**3. Generate user URLs**

> [!WARNING]
>
> Users must authenticate with the toolkits configured in your MCP server first. See [authentication](https://composio-preview.mintlify.site/docs/authentication) for details.

> [tab] Python
>
> ```python theme={null}
> instance = composio.mcp.generate(user_id="user-123", mcp_config_id=server.id)
>
> print(f"MCP Server URL: {instance['url']}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> 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);
> ```

> [tab] API
>
> ```bash theme={null}
> 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**

> [!NOTE]
>
> 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).

> [!WARNING]
>
> For consumer connections, use `https://connect.composio.dev/mcp`, not this URL.

Set `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.

> [tab] OpenAI
>
> > [tab] Python
> >
> > ```python theme={null}
> > 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)
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > 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);
> > ```

> [tab] Anthropic
>
> > [tab] Python
> >
> > > [!NOTE]
> > >
> > > 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](https://composio-preview.mintlify.site/reference/api-reference/mcp). Use the [Claude Agent SDK HTTP transport](https://composio-preview.mintlify.site/docs/sessions-via-mcp.md#wire-it-into-your-framework), which forwards `headers`, instead.
>
> > [tab] TypeScript
> >
> > > [!NOTE]
> > >
> > > 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](https://composio-preview.mintlify.site/reference/api-reference/mcp). Use the [Claude Agent SDK HTTP transport](https://composio-preview.mintlify.site/docs/sessions-via-mcp.md#wire-it-into-your-framework) with the generated URL and headers instead.

> [tab] Mastra
>
> ```typescript theme={null}
> 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

> [tab] Python
>
> ```python theme={null}
> 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)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> 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
> });
> ```

> [tab] API
>
> ```bash theme={null}
> 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

> [tab] Python
>
> ```python theme={null}
> server = composio.mcp.get("mcp_server_id")
> print(f"Server: {server.name}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> 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}`);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X GET https://backend.composio.dev/api/v3.1/mcp/mcp_server_id \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

### Update a server

> [tab] Python
>
> ```python theme={null}
> updated = composio.mcp.update(
>     server_id="mcp_server_id",
>     name="updated-name",
>     allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEARCH_EMAILS"]
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> 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"]
> });
> ```

> [tab] API
>
> ```bash theme={null}
> 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

> [tab] Python
>
> ```python theme={null}
> result = composio.mcp.delete("mcp_server_id")
> if result['deleted']:
>     print("Server deleted")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> 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");
> }
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X DELETE https://backend.composio.dev/api/v3.1/mcp/mcp_server_id \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

## Next

> [card] [Providers](https://composio-preview.mintlify.site/docs/providers)
>
> Use with Anthropic, OpenAI, and other frameworks
