Composio MCP API

openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform Account Management MCP API
  description: MCP server management
  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: MCP
  description: MCP server management
paths:
  /api/v3/mcp/servers:
    get:
      summary: List MCP servers with optional filters and pagination
      description: Retrieves a paginated list of MCP servers associated with the authenticated project. Results can be filtered by name, toolkit, or authentication configuration ID. MCP servers are used to provide Model Control Protocol integration points for connecting AI assistants to your applications and services.
      tags:
      - MCP
      operationId: getMcpServers
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: string
          description: Name substring to filter servers by
          example: github
        required: false
        description: Filter MCP servers by name (case-insensitive partial match)
        name: name
        in: query
      - schema:
          type: string
        required: false
        description: Comma-separated list of toolkit slugs to filter servers by
        in: query
        name: toolkits
      - schema:
          type: string
        required: false
        description: Comma-separated list of auth config IDs to filter servers by
        in: query
        name: auth_config_ids
      - schema:
          type: string
          enum:
          - created_at
          - updated_at
          default: updated_at
          description: Field to use for ordering the results
          example: updated_at
        required: false
        description: Field to order results by
        name: order_by
        in: query
      - schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
          description: Sort direction (ascending or descending)
          example: desc
        required: false
        description: Direction of ordering
        name: order_direction
        in: query
      - schema:
          type: number
          nullable: true
          default: 1
          description: Page number to retrieve
          example: 1
        required: false
        description: Page number for pagination (1-based)
        name: page_no
        in: query
      - schema:
          type: number
          nullable: true
          default: 10
          description: Number of servers to return per page
          example: 10
        required: false
        description: 'Number of items per page (default: 10)'
        name: limit
        in: query
      responses:
        '200':
          description: Successfully retrieved MCP servers. Returns a paginated list of server configurations including connection details and command instructions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: UUID of the MCP server instance
                          example: 550e8400-e29b-41d4-a716-446655440000
                        name:
                          type: string
                          description: User-defined descriptive name for this MCP server
                          example: GitHub 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: Array of tool slugs that this MCP server is allowed to use
                          example:
                          - GITHUB_CREATE_AN_ISSUE
                          - GITHUB_GET_A_REPOSITORY
                          - GITHUB_LIST_PULL_REQUESTS
                        mcp_url:
                          type: string
                          description: '[DEPRECATED] Please use the URL with user_id or connected_account_id query param'
                          deprecated: true
                          example: https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john
                        toolkits:
                          type: array
                          items:
                            type: string
                          description: Array of toolkit slugs that this MCP server is allowed to use
                          example:
                          - github
                          - jira
                          - slack
                        toolkit_icons:
                          type: object
                          additionalProperties:
                            type: string
                          description: Object mapping each toolkit slug to its icon/logo URL for display purposes
                          example:
                            github: https://assets.composio.dev/logos/github.png
                            jira: https://assets.composio.dev/logos/jira.png
                            slack: https://assets.composio.dev/logos/slack.png
                        commands:
                          type: object
                          properties:
                            cursor:
                              type: string
                              description: Command line instruction for Cursor client setup
                              deprecated: true
                              example: npx @composio/mcp@latest setup "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john" --client cursor
                            claude:
                              type: string
                              description: Command line instruction for Claude client setup
                              deprecated: true
                              example: npx @composio/mcp@latest setup "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john" --client claude
                            windsurf:
                              type: string
                              description: Command line instruction for Windsurf client setup
                              deprecated: true
                              example: npx @composio/mcp@latest setup "https://backend.composio.dev/v3/mcp/550e8400-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
                          deprecated: true
                        updated_at:
                          type: string
                          description: Date and time when this server configuration was last modified
                          example: '2023-06-15T14:30:00.000Z'
                        created_at:
                          type: string
                          description: Date and time when this server was initially created
                          example: '2023-06-10T09:15:00.000Z'
                        server_instance_count:
                          type: number
                          description: Total count of active user instances connected to this server
                          example: 5
                        managed_auth_via_composio:
                          type: boolean
                          description: Whether the MCP server is managed by Composio
                          example: true
                      required:
                      - id
                      - name
                      - auth_config_ids
                      - allowed_tools
                      - mcp_url
                      - toolkits
                      - toolkit_icons
                      - commands
                      - updated_at
                      - created_at
                      - server_instance_count
                      - managed_auth_via_composio
                      description: MCP server configuration and connection details
                    description: Array of MCP server configurations
                    example:
                    - id: 550e8400-e29b-41d4-a716-446655440000
                      name: GitHub Integration Server
                      auth_config_ids:
                      - ac_1a2b3c4d5e6f
                      - ac_7g8h9i0j1k2l
                      allowed_tools:
                      - GITHUB_CREATE_AN_ISSUE
                      - GITHUB_GET_A_REPOSITORY
                      mcp_url: https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john
                      commands:
                        cursor: npx @composio/mcp@latest setup "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john" --client cursor
                        claude: npx @composio/mcp@latest setup "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john" --client claude
                        windsurf: npx @composio/mcp@latest setup "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john" --client windsurf
                      toolkits:
                      - github
                      - jira
                      - slack
                      toolkit_icons:
                        github: https://assets.composio.dev/logos/github.png
                        jira: https://assets.composio.dev/logos/jira.png
                        slack: https://assets.composio.dev/logos/slack.png
                      updated_at: '2023-06-15T14:30:00.000Z'
                      created_at: '2023-06-10T09:15:00.000Z'
                      server_instance_count: 5
                      managed_auth_via_composio: true
                  total_pages:
                    type: number
                    description: Total number of pages in the paginated response
                    example: 5
                  current_page:
                    type: number
                    description: Current page number being returned
                    example: 1
                required:
                - items
                - total_pages
                - current_page
                description: Paginated response containing MCP servers
        '400':
          description: Bad request. The query parameters may be invalid or in an incorrect format.
          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 view 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'
    post:
      summary: Create a new MCP server
      description: Creates a new Model Control Protocol (MCP) server instance for the authenticated project. An MCP server provides a connection point for AI assistants to access your applications and services. The server is configured with specific authentication and tool permissions that determine what actions the connected assistants can perform.
      tags:
      - MCP
      operationId: postMcpServers
      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 MCP server instance (4-30 characters, alphanumeric, spaces, and hyphens only)
                  example: Production GitHub Integration
                auth_config_ids:
                  type: array
                  items:
                    type: string
                  description: ID references to existing authentication configurations
                  example:
                  - ac_1a2b3c4d5e6f
                  - ac_7g8h9i0j1k2l
                no_auth_apps:
                  type: array
                  items:
                    type: string
                  description: List of NO_AUTH apps to enable for this MCP server
                  example:
                  - exa
                  - codeinterpreter
                  - composio
                  - composio_search
                allowed_tools:
                  type: array
                  items:
                    type: string
                  default: []
                  description: List of tool slugs that should be allowed for this server. If not provided, all available tools for the authentication configuration will be enabled.
                  example:
                  - GITHUB_CREATE_AN_ISSUE
                  - GITHUB_GET_A_REPOSITORY
                  - GITHUB_LIST_PULL_REQUESTS
                managed_auth_via_composio:
                  type: boolean
                  description: Whether the MCP server is managed by Composio
              required:
              - name
              - auth_config_ids
              description: Request parameters for creating a new MCP server with specific authentication configuration
            examples:
              Basic MCP Server:
                value:
                  name: GitHub Integration Server
                  auth_config_ids:
                  - ac_1a2b3c4d5e6f
              Server with Limited Tools:
                value:
                  name: GitHub Issues Only
                  auth_config_ids:
                  - ac_1a2b3c4d5e6f
                  allowed_tools:
                  - GMAIL_ADD_LABEL_TO_EMAIL
              Server with Expiration:
                value:
                  name: Temporary Integration Server
                  auth_config_ids:
                  - ac_1a2b3c4d5e6f
      responses:
        '201':
          description: MCP server created successfully. Returns the complete server configuration including connection details and command instructions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: UUID of the MCP server instance
                    example: 550e8400-e29b-41d4-a716-446655440000
                  name:
                    type: string
                    description: User-defined descriptive name for this MCP server
                    example: GitHub 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: Array of tool slugs that this MCP server is allowed to use
                    example:
                    - GITHUB_CREATE_AN_ISSUE
                    - GITHUB_GET_A_REPOSITORY
                    - GITHUB_LIST_PULL_REQUESTS
                  mcp_url:
                    type: string
                    description: '[DEPRECATED] Please use the URL with user_id or connected_account_id query param'
                    deprecated: true
                    example: https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john
                  toolkits:
                    type: array
                    items:
                      type: string
                    description: Array of toolkit slugs that this MCP server is allowed to use
                    example:
                    - github
                    - jira
                    - slack
                  toolkit_icons:
                    type: object
                    additionalProperties:
                      type: string
                    description: Object mapping each toolkit slug to its icon/logo URL for display purposes
                    example:
                      github: https://assets.composio.dev/logos/github.png
                      jira: https://assets.composio.dev/logos/jira.png
                      slack: https://assets.composio.dev/logos/slack.png
                  commands:
                    type: object
                    properties:
                      cursor:
                        type: string
                        description: Command line instruction for Cursor client setup
                        deprecated: true
                        example: npx @composio/mcp@latest setup "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john" --client cursor
                      claude:
                        type: string
                        description: Command line instruction for Claude client setup
                        deprecated: true
                        example: npx @composio/mcp@latest setup "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john" --client claude
                      windsurf:
                        type: string
                        description: Command line instruction for Windsurf client setup
                        deprecated: true
                        example: npx @composio/mcp@latest setup "https://backend.composio.dev/v3/mcp/550e8400-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
                    deprecated: true
                  updated_at:
                    type: string
                    description: Date and time when this server configuration was last modified
                    example: '2023-06-15T14:30:00.000Z'
                  created_at:
                    type: string
                    description: Date and time when this server was initially created
                    example: '2023-06-10T09:15:00.000Z'
                  server_instance_count:
                    type: number
                    description: Total count of active user instances connected to this server
                    example: 5
                  managed_auth_via_composio:
                    type: boolean
                    description: Whether the MCP server is managed by Composio
                    example: true
                required:
                - id
                - name
                - auth_config_ids
                - allowed_tools
                - mcp_url
                - toolkits
                - toolkit_icons
                - commands
                - updated_at
                - created_at
                - server_instance_count
                - managed_auth_via_composio
                description: MCP server configuration and connection details
        '400':
          description: Bad request. The request body may be invalid, missing required parameters, or the auth_config_id may not exist.
          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. The specified auth_config_id does not exist or is not accessible to the authenticated user.
          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'
  /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:
      - MCP
      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'
  /api/v3/mcp/servers/generate:
    post:
      summary: Generate MCP URL with custom parameters
      description: Generates a Model Control Protocol (MCP) URL for an existing server with custom query parameters. The URL includes user-specific parameters and configuration flags that control the behavior of the MCP connection.
      tags:
      - MCP
      operationId: postMcpServersGenerate
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mcp_server_id:
                  type: string
                  description: Unique identifier of the MCP server to generate URL for
                  example: 550e8400-e29b-41d4-a716-446655440000
                managed_auth_by_composio:
                  type: boolean
                  default: false
                  description: Flag indicating if Composio manages authentication
                  example: true
                user_ids:
                  type: array
                  items:
                    type: string
                  description: List of user identifiers for whom the URL is generated
                  example:
                  - user_123456
                  - user_789012
                connected_account_ids:
                  type: array
                  items:
                    type: string
                  description: List of connected account identifiers
                  example:
                  - ca_1a2b3c4d5e6f
                  - ca_7g8h9i0j1k2l
                  - ca_3m4n5o6p7q8r
              required:
              - mcp_server_id
              description: Request parameters for generating an MCP URL
            examples:
              Basic URL Generation:
                value:
                  mcp_server_id: 550e8400-e29b-41d4-a716-446655440000
                  user_ids:
                  - user_123456
                  connected_account_ids:
                  - ca_1a2b3c4d5e6f
                  - ca_7g8h9i0j1k2l
              Managed Auth Configuration:
                value:
                  mcp_server_id: 550e8400-e29b-41d4-a716-446655440000
                  user_ids:
                  - user_123456
                  - user_789012
                  connected_account_ids:
                  - ca_1a2b3c4d5e6f
                  - ca_7g8h9i0j1k2l
                  - ca_3m4n5o6p7q8r
      responses:
        '200':
          description: Successfully generated MCP URL. Returns the complete URL with all specified query parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  mcp_url:
                    type: string
                    description: Base MCP URL without any query parameters
                    example: https://mcp.composio.dev/composio/server/550e8400-e29b-41d4-a716-446655440000
                  connected_account_urls:
                    type: array
                    items:
                      type: string
                    description: List of URLs generated for each connected account ID

# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/composio/refs/heads/main/openapi/composio-mcp-api-openapi.yml