> ## 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.

# Create a new custom MCP server with multiple apps

> Creates a new Model Control Protocol (MCP) server instance that can integrate with multiple applications or toolkits simultaneously. This endpoint allows you to create a server that can access tools from different applications, making it suitable for complex workflows that span multiple services.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v3.1/mcp/servers/custom
openapi: 3.1.0
info:
  version: 3.1.0
  title: Composio Platform API v3.1
  description: >-
    Composio v3.1 API — all endpoints available under /api/v3.1/. Tool endpoints
    default to the latest tool version.
  contact:
    name: Composio Support
    url: https://composio.dev/support
    email: support@composio.dev
  license:
    name: Proprietary
    url: https://composio.dev/terms
servers:
  - url: https://backend.composio.dev
    description: Composio production API
security:
  - ApiKeyAuth: []
tags:
  - name: Authentication
    description: Authentication related endpoints
    x-group: Authentication
  - name: Auth Configs
    description: Authentication configuration management
    x-group: Auth Configs
  - name: Connected Accounts
    description: Connected account management
    x-group: Connected Accounts
  - name: Logs
    description: Logging and monitoring
    x-group: Logs
  - name: OpenAPI
    description: OpenAPI specification management
    x-group: OpenAPI
  - name: Organization
    description: Organization management
    x-group: Organization
  - name: API Keys
    description: API key management
    x-group: API Keys
  - name: Webhooks
    description: Webhook configuration
    x-group: Webhooks
  - name: Webhook Endpoints
    description: >-
      Per-OAuth-app webhook ingress endpoints. Inbound URLs the provider posts
      to, plus signing secret storage and verification.
    x-group: Webhook Endpoints
  - name: Webhook Subscriptions
    description: >-
      Webhook delivery subscriptions. Outbound URLs Composio posts trigger
      events to, plus signing secret rotation and event-type filters.
    x-group: Webhook Subscriptions
  - name: Team
    description: Team member management
    x-group: Team
  - name: Consumer Skills
    description: Organization-authored Skill management
    x-group: Consumer Skills
  - name: Toolkits
    description: Toolkit and tool management
    x-group: Toolkits
  - name: Tools
    description: Tool execution endpoints
    x-group: Tools
  - name: Triggers
    description: Trigger management and execution
    x-group: Triggers
  - name: Payments
    description: Payment and subscription management
    x-group: Payments
  - name: Billing
    description: Dashboard billing state — usage, subscription, contract (cookie-auth only)
    x-group: Billing
  - name: Compliance
    description: Organization compliance agreements and acceptance state
    x-group: Compliance
  - name: Files
    description: File management
    x-group: Files
  - name: MCP
    description: MCP server management
    x-group: MCP
  - name: MCP Partner
    description: MCP partner management
    x-group: MCP Partner
  - name: Stripe Projects
    description: Stripe Projects provisioning
    x-group: Stripe Projects
  - name: Tool Router
    description: (Labs) Tool router endpoints
    x-group: Sessions (Prev Tool Router)
  - name: Playground
    description: Dashboard playground chat
    x-group: Playground
  - name: Arena
    description: Arena conversations, messages and terms
    x-group: Arena
  - name: Projects
    description: Projects API endpoints.
    x-group: Projects
  - name: Organization Management
    description: Organization Management API endpoints.
    x-group: Organization Management
  - name: Webhook Events
    description: Events delivered by Composio to your registered webhook endpoints
    x-group: Webhook Events
paths:
  /api/v3.1/mcp/servers/custom:
    post:
      tags:
        - MCP
      summary: Create a new custom MCP server with multiple apps
      description: >-
        Creates a new Model Control Protocol (MCP) server instance that can
        integrate with multiple applications or toolkits simultaneously. This
        endpoint allows you to create a server that can access tools from
        different applications, making it suitable for complex workflows that
        span multiple services.
      operationId: postMcpServersCustom
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 4
                  maxLength: 30
                  pattern: ^[a-zA-Z0-9- ]+$
                  description: >-
                    Human-readable name to identify this custom MCP server (4-30
                    characters, alphanumeric, spaces, and hyphens only)
                  example: Multi App Integration Server
                auth_config_ids:
                  type: array
                  items:
                    type: string
                  description: ID references to existing authentication configurations
                  example:
                    - ac_1a2b3c4d5e6f
                    - ac_7g8h9i0j1k2l
                toolkits:
                  type: array
                  items:
                    type: string
                  description: >-
                    List of application/toolkit identifiers to enable for this
                    server
                  example:
                    - github
                    - jira
                    - slack
                allowed_tools:
                  type: array
                  items:
                    type: string
                  description: >-
                    Tool identifiers to enable that aren't part of standard
                    toolkits
                  example:
                    - GITHUB_CREATE_AN_ISSUE
                    - SLACK_SEND_MESSAGE
                custom_tools:
                  type: array
                  items:
                    type: string
                  description: >-
                    DEPRECATED: Use allowed_tools instead. Tool identifiers to
                    enable that aren't part of standard toolkits
                  example:
                    - GITHUB_CREATE_AN_ISSUE
                    - SLACK_SEND_MESSAGE
                managed_auth_via_composio:
                  type: boolean
                  description: Whether to manage authentication via Composio
              required:
                - name
              description: >-
                Parameters for creating a new custom MCP server with multiple
                applications
            examples:
              Basic Multi-App Server:
                value:
                  name: Development Integration Server
                  toolkits:
                    - github
                    - jira
              Advanced Multi-App Server:
                value:
                  name: Complete Workflow Integration
                  toolkits:
                    - github
                    - jira
                    - slack
                  custom_tools:
                    - SLACK_SEND_MESSAGE
      responses:
        '201':
          description: >-
            Custom MCP server created successfully. Returns the complete server
            configuration including connection details and command instructions
            for all specified applications.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier for the newly created custom MCP server
                    example: 550e8400-e29b-41d4-a716-446655440000
                  name:
                    type: string
                    description: Human-readable name of the custom MCP server
                    example: Multi-App Integration Server
                  auth_config_ids:
                    type: array
                    items:
                      type: string
                    description: >-
                      ID references to the auth configurations used by this
                      server
                    example:
                      - ac_1a2b3c4d5e6f
                      - ac_7g8h9i0j1k2l
                  allowed_tools:
                    type: array
                    items:
                      type: string
                    description: List of tool identifiers that are enabled for this server
                    example:
                      - GITHUB_CREATE_AN_ISSUE
                      - JIRA_GET_ISSUE
                      - SLACK_SEND_MESSAGE
                      - GMAIL_SEND_EMAIL
                  mcp_url:
                    type: string
                    description: >-
                      URL endpoint for establishing connection to this MCP
                      server
                    example: >-
                      https://backend.composio.dev/v3/mcp/550e8410-e29b-41d4-a716-446655440000?user_id=john
                  commands:
                    type: object
                    properties:
                      cursor:
                        type: string
                        description: Command line instruction for Cursor client setup
                        example: >-
                          npx @composio/mcp@latest setup
                          "https://backend.composio.dev/v3/mcp/550e8410-e29b-41d4-a716-446655440000?user_id=john"
                          --client cursor
                      claude:
                        type: string
                        description: Command line instruction for Claude client setup
                        example: >-
                          npx @composio/mcp@latest setup
                          "https://backend.composio.dev/v3/mcp/550e8410-e29b-41d4-a716-446655440000?user_id=john"
                          --client claude
                      windsurf:
                        type: string
                        description: Command line instruction for Windsurf client setup
                        example: >-
                          npx @composio/mcp@latest setup
                          "https://backend.composio.dev/v3/mcp/550e8410-e29b-41d4-a716-446655440000?user_id=john"
                          --client windsurf
                    required:
                      - cursor
                      - claude
                      - windsurf
                    description: >-
                      Set of command line instructions for connecting various
                      clients to this MCP server
                required:
                  - id
                  - name
                  - auth_config_ids
                  - allowed_tools
                  - mcp_url
                  - commands
                description: >-
                  Response for a successfully created custom MCP server with
                  multiple applications
        '400':
          description: >-
            Bad request. The request body may be invalid, missing required
            parameters, or contain invalid toolkit identifiers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            Unauthorized. Authentication is required or the provided credentials
            are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Forbidden. The authenticated user does not have permission to create
            MCP servers for this project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            Not Found. One or more of the specified auth_config_ids do not exist
            or are not accessible to the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            Conflict. A custom MCP server with the specified name already exists
            in this project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: >-
            Internal server error. An unexpected error occurred while processing
            the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      deprecated: true
      security:
        - ApiKeyAuth: []
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: number
            slug:
              type: string
            status:
              type: number
            request_id:
              type: string
            suggested_fix:
              type: string
            errors:
              type: array
              items:
                type: string
          required:
            - message
            - code
            - slug
            - status
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Composio project API key. Create or copy it from the Composio
        dashboard.
      x-default: your-project-api-key

````