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

# List MCP servers with optional filters and pagination

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



## OpenAPI

````yaml api-reference/openapi-v3.json GET /api/v3/mcp/servers
openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform API
  description: >-
    Composio v3 API — legacy endpoints under /api/v3/. Use v3.1 for new
    integrations.
  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: Organization Management
    description: Organization Management API endpoints.
    x-group: Organization Management
  - name: Projects
    description: Projects API endpoints.
    x-group: Projects
paths:
  /api/v3/mcp/servers:
    get:
      tags:
        - MCP
      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.
      operationId: getMcpServers
      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: integer
            minimum: 0
            exclusiveMinimum: 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: integer
            minimum: 0
            exclusiveMinimum: 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'
        '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'
        '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

````