> ## 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 custom toolkit

> Experimental: this endpoint may change. Creates a custom MCP toolkit and returns its slug. Set user_id to "all" to share the toolkit with every user in the project, or to a user ID to make it private to that user ("default" and other spellings of "all" are rejected). Access cannot be changed later. For a private toolkit, the response can include a connect_link to send that user to.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v3.1/custom/toolkits
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/custom/toolkits:
    post:
      tags:
        - Toolkits
      summary: Create a custom toolkit
      description: >-
        Experimental: this endpoint may change. Creates a custom MCP toolkit and
        returns its slug. Set user_id to "all" to share the toolkit with every
        user in the project, or to a user ID to make it private to that user
        ("default" and other spellings of "all" are rejected). Access cannot be
        changed later. For a private toolkit, the response can include a
        connect_link to send that user to.
      operationId: postCustomToolkits
      requestBody:
        required: true
        description: Toolkit to create
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 200
                  description: Display name of the toolkit
                app_url:
                  type: string
                  format: uri
                  description: MCP server URL. Must use https.
                logo_file:
                  type: object
                  properties:
                    content:
                      type: string
                      minLength: 1
                      maxLength: 4000000
                      pattern: ^[A-Za-z0-9+/]+={0,2}$
                      description: Base64-encoded image, max 3MB decoded
                    mime_type:
                      type: string
                      enum:
                        - image/png
                        - image/jpeg
                      description: Image MIME type
                  required:
                    - content
                    - mime_type
                  additionalProperties: false
                  description: >-
                    Square PNG or JPEG logo, 256-1024px, max 3MB. Defaults to
                    the Model Context Protocol logo.
                auth_schemes:
                  type: array
                  items:
                    oneOf:
                      - type: object
                        properties:
                          mode:
                            type: string
                            enum:
                              - NO_AUTH
                        required:
                          - mode
                        additionalProperties: false
                      - type: object
                        properties:
                          mode:
                            type: string
                            enum:
                              - API_KEY
                          headers:
                            type: object
                            additionalProperties:
                              type: string
                            description: >-
                              Headers sent to the MCP server. Use
                              {{generic_api_key}} where the API key goes.
                          api_key_field:
                            type: object
                            properties:
                              display_name:
                                type: string
                                minLength: 1
                                maxLength: 100
                                description: Label for the API key input
                              description:
                                type: string
                                minLength: 1
                                maxLength: 500
                                description: Help text below the API key input
                            additionalProperties: false
                            description: >-
                              Label and help text for the API key input on the
                              connect page
                          additional_fields:
                            type: object
                            properties:
                              generic_id:
                                type: object
                                properties:
                                  display_name:
                                    type: string
                                    minLength: 1
                                    maxLength: 100
                                    description: >-
                                      Label shown to the user connecting their
                                      account
                                  description:
                                    type: string
                                    minLength: 1
                                    maxLength: 500
                                    description: Help text below the input
                                required:
                                  - display_name
                                additionalProperties: false
                            required:
                              - generic_id
                            additionalProperties: false
                            description: >-
                              Additional values each user enters when
                              connecting. Reference each field in a header, for
                              example X-Org-Id: {{generic_id}}. Use display_name
                              for the user-facing label. Every user must supply
                              each declared field. Values are not secret.
                        required:
                          - mode
                          - headers
                        additionalProperties: false
                      - type: object
                        properties:
                          mode:
                            type: string
                            enum:
                              - DCR_OAUTH
                          discovery_url:
                            type: string
                            format: uri
                            description: >-
                              OAuth authorization server metadata URL, for
                              example https://<auth server
                              host>/.well-known/oauth-authorization-server. Use
                              the URL your authorization server publishes; it
                              can be on a different host from the MCP server or
                              include a path.
                            example: >-
                              https://mcp.example.com/.well-known/oauth-authorization-server
                        required:
                          - mode
                          - discovery_url
                        additionalProperties: false
                  minItems: 1
                  description: How users authenticate to the MCP server
                user_id:
                  anyOf:
                    - type: string
                      enum:
                        - all
                    - type: string
                      minLength: 1
                      maxLength: 256
                  description: >-
                    "all" to share the toolkit with every user in the project,
                    or a user ID to make it private to that user. "default" and
                    other spellings of "all" (such as "ALL" or " all") are
                    rejected. Cannot be changed after create.
                  example: all
                callback_url:
                  type: string
                  format: uri
                  description: >-
                    URL to send the user to after they connect. Used only for
                    connect_link.
              required:
                - name
                - app_url
                - auth_schemes
                - user_id
              additionalProperties: false
      responses:
        '200':
          description: Successfully created toolkit
          content:
            application/json:
              schema:
                type: object
                properties:
                  slug:
                    type: string
                    description: Slug of the created toolkit
                    example: CUSTOM_NOTION_K7F2Q
                  connect_link:
                    type:
                      - object
                      - 'null'
                    properties:
                      redirect_url:
                        type: string
                        description: Hosted connect page. Send the user here.
                      expires_at:
                        type: string
                        description: When the link expires (ISO 8601)
                      connected_account_id:
                        type: string
                        format: connectedAccountId
                        description: >-
                          Connected account for the user. It becomes ACTIVE once
                          they connect.
                    required:
                      - redirect_url
                      - expires_at
                      - connected_account_id
                    description: >-
                      Link for a private toolkit's user to connect. Null for
                      shared or no-auth toolkits, or if the link could not be
                      created. To retry, call POST
                      /api/v3.1/connected_accounts/link with an auth config for
                      the toolkit, creating one with POST /api/v3.1/auth_configs
                      if needed.
                required:
                  - slug
                  - connect_link
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Your role cannot create custom toolkits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '408':
          description: Request timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict - This user already has a private toolkit for this MCP URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests - Retry after a short backoff
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error - Failed to create toolkit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
        - UserApiKeyAuth: []
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
    UserApiKeyAuth:
      type: apiKey
      in: header
      name: x-user-api-key
      description: Your Composio user API key for user-scoped endpoints.
      x-default: your-user-api-key

````