> ## 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 MCP server

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



## OpenAPI

````yaml api-reference/openapi.json POST /api/v3.1/mcp/servers
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:
    post:
      tags:
        - MCP
      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.
      operationId: postMcpServers
      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'
        '409':
          description: >-
            Conflict. An 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

````