> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add an MCP Gateway connector

> Add a connector and return it with its `setupStatus` and `cockpitUrl`. `definition.source` `catalog` takes a `catalogKey` from `getMcpGatewayCatalog`, a `credentialMode` the entry supports, and optionally a `name` and a `toolPrefix` (the entry's by default). `custom` takes a `name`, a `toolPrefix`, the `serverUrl` (https, origin and path: a query or a fragment is refused with a 400, so a token never travels in the address), the `transport`, the `authentication` (its type and header names or OAuth client id, never a secret) and the `credentialMode`. A catalog connector starts enabled; a custom one starts disabled, until IT reads its tools and enables it in the cockpit. Either way no tool is served before IT lists its tools there, and connects the account of a `shared` one. A 404 means the catalog key is unknown, a 409 that the tool prefix is taken. Nothing here changes or enables an existing connector: that is done in the cockpit. The MCP Gateway serves employees, through their one Primo connection, the tools of the MCP servers (connectors) IT added. No credential is ever sent or returned here: IT connects a shared account, lists the tools and sets their policy in the cockpit, at `cockpitUrl`. A company without the MCP Gateway gets a 403 `McpGatewayNotEnabledError`; a 503 means Primo could not check it, try again in a minute.

Key: WriteScope: Company


## OpenAPI

````yaml https://api.getprimo.com/openapi.json post /mcp-gateway/connectors
openapi: 3.1.1
info:
  title: Public API - BETA
  description: Read docs on https://docs.getprimo.com/
  version: '1.0'
  contact: {}
servers:
  - url: https://api.getprimo.com
security:
  - apikey: []
tags: []
paths:
  /mcp-gateway/connectors:
    post:
      tags:
        - McpGateway
      summary: Add an MCP Gateway connector
      description: >-
        Add a connector and return it with its `setupStatus` and `cockpitUrl`.
        `definition.source` `catalog` takes a `catalogKey` from
        `getMcpGatewayCatalog`, a `credentialMode` the entry supports, and
        optionally a `name` and a `toolPrefix` (the entry's by default).
        `custom` takes a `name`, a `toolPrefix`, the `serverUrl` (https, origin
        and path: a query or a fragment is refused with a 400, so a token never
        travels in the address), the `transport`, the `authentication` (its type
        and header names or OAuth client id, never a secret) and the
        `credentialMode`. A catalog connector starts enabled; a custom one
        starts disabled, until IT reads its tools and enables it in the cockpit.
        Either way no tool is served before IT lists its tools there, and
        connects the account of a `shared` one. A 404 means the catalog key is
        unknown, a 409 that the tool prefix is taken. Nothing here changes or
        enables an existing connector: that is done in the cockpit. The MCP
        Gateway serves employees, through their one Primo connection, the tools
        of the MCP servers (connectors) IT added. No credential is ever sent or
        returned here: IT connects a shared account, lists the tools and sets
        their policy in the cockpit, at `cockpitUrl`. A company without the MCP
        Gateway gets a 403 `McpGatewayNotEnabledError`; a 503 means Primo could
        not check it, try again in a minute.
      operationId: createMcpGatewayConnector
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMcpGatewayConnectorBody'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMcpGatewayConnectorResponse_Output'
components:
  schemas:
    CreateMcpGatewayConnectorBody:
      type: object
      properties:
        definition:
          anyOf:
            - type: object
              properties:
                source:
                  type: string
                  const: catalog
                catalogKey:
                  description: The `key` of an entry of `getMcpGatewayCatalog`
                  type: string
                  minLength: 1
                  maxLength: 64
                credentialMode:
                  description: >-
                    `per_employee`: each employee connects their own account;
                    `shared`: IT connects one account that every employee uses
                  type: string
                  enum:
                    - per_employee
                    - shared
                name:
                  description: Defaults to the entry's name
                  type: string
                  minLength: 1
                  maxLength: 80
                toolPrefix:
                  description: Defaults to the entry's `defaultToolPrefix`
                  type: string
                  minLength: 1
                  maxLength: 64
              required:
                - source
                - catalogKey
                - credentialMode
            - type: object
              properties:
                source:
                  type: string
                  const: custom
                name:
                  description: The name employees and IT see
                  type: string
                  minLength: 1
                  maxLength: 80
                toolPrefix:
                  description: >-
                    What the names of its tools start with, unique in the
                    company
                  type: string
                  minLength: 1
                  maxLength: 64
                serverUrl:
                  description: >-
                    The https address of the MCP server, origin and path: a
                    query or a fragment is refused
                  type: string
                  maxLength: 2048
                  format: uri
                transport:
                  description: >-
                    How the gateway talks to the server: `streamable_http`, or
                    `sse` for an older server
                  type: string
                  enum:
                    - streamable_http
                    - sse
                authentication:
                  description: >-
                    How the server is signed in to, never a secret:
                    `oauth_dynamic`, `oauth_client` with its client id,
                    `header_token` with its header name and scheme,
                    `custom_headers` with their names, or `none`
                  anyOf:
                    - type: object
                      properties:
                        type:
                          type: string
                          const: oauth_dynamic
                        scopes:
                          maxItems: 50
                          type: array
                          items:
                            type: string
                            minLength: 1
                            maxLength: 256
                      required:
                        - type
                    - type: object
                      properties:
                        type:
                          type: string
                          const: oauth_client
                        clientId:
                          type: string
                          minLength: 1
                          maxLength: 512
                        scopes:
                          maxItems: 50
                          type: array
                          items:
                            type: string
                            minLength: 1
                            maxLength: 256
                      required:
                        - type
                        - clientId
                    - type: object
                      properties:
                        type:
                          type: string
                          const: header_token
                        headerName:
                          description: Defaults to Authorization
                          type: string
                          minLength: 1
                          maxLength: 128
                          pattern: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$
                        scheme:
                          description: For instance Bearer; none by default
                          anyOf:
                            - type: string
                              minLength: 1
                              maxLength: 64
                            - type: 'null'
                      required:
                        - type
                    - type: object
                      properties:
                        type:
                          type: string
                          const: custom_headers
                        headerNames:
                          minItems: 1
                          maxItems: 10
                          type: array
                          items:
                            type: string
                            minLength: 1
                            maxLength: 128
                            pattern: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$
                      required:
                        - type
                        - headerNames
                    - type: object
                      properties:
                        type:
                          type: string
                          const: none
                      required:
                        - type
                credentialMode:
                  description: >-
                    `per_employee`: each employee connects their own account;
                    `shared`: IT connects one account that every employee uses
                  type: string
                  enum:
                    - per_employee
                    - shared
              required:
                - source
                - name
                - toolPrefix
                - serverUrl
                - transport
                - authentication
                - credentialMode
      required:
        - definition
    CreateMcpGatewayConnectorResponse_Output:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        toolPrefix:
          description: What the names of its tools start with
          type: string
        source:
          description: '`catalog` (an entry of the catalog) or `custom` (an address)'
          type: string
          enum:
            - catalog
            - custom
        catalogKey:
          description: The `key` of its catalog entry, null for a custom connector
          anyOf:
            - type: string
            - type: 'null'
        serverUrl:
          description: The origin and the path of the server, never its query or fragment
          type: string
        transport:
          description: >-
            How the gateway talks to the server: `streamable_http`, or `sse` for
            an older server
          type: string
          enum:
            - streamable_http
            - sse
        authentication:
          description: >-
            How the server is signed in to: OAuth (`oauth_dynamic`, or
            `oauth_client` with its client id), a token in a header
            (`header_token`, its header name and scheme), several headers
            (`custom_headers`, their names) or `none`. Never a secret: the
            credential itself is connected in the cockpit
          anyOf:
            - type: object
              properties:
                type:
                  type: string
                  const: oauth_dynamic
                scopes:
                  type: array
                  items:
                    type: string
              required:
                - type
                - scopes
              additionalProperties: false
            - type: object
              properties:
                type:
                  type: string
                  const: oauth_client
                clientId:
                  type: string
                scopes:
                  type: array
                  items:
                    type: string
              required:
                - type
                - clientId
                - scopes
              additionalProperties: false
            - type: object
              properties:
                type:
                  type: string
                  const: header_token
                headerName:
                  type: string
                scheme:
                  anyOf:
                    - type: string
                    - type: 'null'
              required:
                - type
                - headerName
                - scheme
              additionalProperties: false
            - type: object
              properties:
                type:
                  type: string
                  const: custom_headers
                headerNames:
                  type: array
                  items:
                    type: string
              required:
                - type
                - headerNames
              additionalProperties: false
            - type: object
              properties:
                type:
                  type: string
                  const: none
              required:
                - type
              additionalProperties: false
        credentialMode:
          description: >-
            `per_employee`: each employee connects their own account; `shared`:
            IT connects one account that every employee uses
          type: string
          enum:
            - per_employee
            - shared
        enabled:
          description: Whether employees are served its tools; IT enables it in the cockpit
          type: boolean
        createdAt:
          type: string
        updatedAt:
          type: string
        listedToolCount:
          description: How many tools its snapshot lists
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        setupStatus:
          description: >-
            The first thing IT still has to do in the cockpit before it serves
            its tools, or `ready`
          type: string
          enum:
            - disabled
            - no_tools_listed
            - shared_credential_missing
            - shared_credential_to_reconnect
            - employees_connect_themselves
            - ready
        cockpitUrl:
          description: Its page in the cockpit, where IT finishes its setup
          type: string
      required:
        - id
        - name
        - toolPrefix
        - source
        - catalogKey
        - serverUrl
        - transport
        - authentication
        - credentialMode
        - enabled
        - createdAt
        - updatedAt
        - listedToolCount
        - setupStatus
        - cockpitUrl
      additionalProperties: false
  securitySchemes:
    apikey:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: >-
        Use your Primo API key in the Authorization header as `Bearer
        <API_KEY>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.