Composio Custom API

openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform Account Management Custom API
  description: ''
  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: PRODUCTION API
tags:
- name: Custom
paths:
  /api/v3/mcp/servers/custom:
    post:
      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.
      tags:
      - Custom
      operationId: postMcpServersCustom
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      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'
        '500':
          description: Internal server error. An unexpected error occurred while processing the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
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: Project API key authentication
    UserApiKeyAuth:
      type: apiKey
      in: header
      name: x-user-api-key
      description: User API key authentication
    CookieAuth:
      type: apiKey
      in: cookie
      name: authToken
      description: Cookie-based session authentication
    OrgApiKeyAuth:
      type: apiKey
      in: header
      name: x-org-api-key
      description: Organization API key authentication