OPopenworklabs
Capability Sources

Create or replace an External MCP Connection by stable key

Changed on

Declarative upsert; needs the Manage connections permission (owners and admins by default). Creates a connection when the organization has not used the key, otherwise replaces the keyed connection without changing its stable identity. Replacing a connection someone else created also needs Edit any connection, and making a connection org-wide needs Share with everyone.

put/v1/mcp-connections/by-key/{externalKey}

Request

  • Base URL
    https://api.openworklabs.com
  • URL
    https://api.openworklabs.com/v1/mcp-connections/by-key/{externalKey}
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Path parameters

externalKeystring required

Client-chosen stable identifier, unique per organization. Immutable.

Headers

If-Matchstring date-time

Existing connection updatedAt timestamp required by the caller for conditional replacement.

Request body

kind'external_mcp'
namestring required
urlstring uri required
authType'oauth' | 'apikey' | 'none' required
credentialMode'shared' | 'per_member'
exposeDirectlyboolean
apiKeystring
apiKeyAuthScheme'bearer' | 'token'
authorizationServerIssuerstring uri nullable
requestedScopesstring[]

Response

Connection updated.

idstring required
namestring required
externalKeystring nullable required
urlstring required
authType'oauth' | 'apikey' | 'none' required
credentialMode'shared' | 'per_member' required
apiKeyAuthScheme'bearer' | 'token' required
requestHeaderNamesstring[] required
exposeDirectlyboolean required
mcpUrlstring uri
connectedboolean required
connectedAtstring date-time nullable required
createdByNamestring nullable
createdByYouboolean
canRemoveboolean
createdAtstring date-time
updatedAtstring date-time required
connectedForMeboolean required
needsReconnectboolean
credentialHealth'unknown' | 'ready' | 'reconnect_required'
credentialHealthReason'authorization_rejected' | 'credential_expired' | 'post_authorization_validation_failed' nullable
credentialHealthCheckedAtstring date-time nullable
issuerReviewRequiredboolean
reconnectActionOwner'member' | 'organization_admin' nullable
missingFeaturesstring[]
externalAccountIdstring nullable
grantedScopesstring[]
tenantIdstring nullable
requiredAuthType'oauth' | 'apikey' | 'none' nullable
authPolicyConfirmedboolean
authTypeMismatchboolean
oauthClientConfiguredboolean
oauthClientRequiredboolean
setupRequiredboolean
oauthClientIdstring nullable
oauthClientHasSecretboolean

Whether a client secret is configured. Only returned with explicit connection-settings view permission; never the secret itself.

oauthCallbackUrlstring nullable
oauthSharedCallbackUrlstring nullable
oauthClientMetadataUrlstring nullable
oauthCallbackMode'shared-v1' | 'isolated-v1' | 'legacy-v1' nullable
oauthRegistrationSource'pre-registered' | 'client-metadata' | 'dynamic' nullable
authorizationServerIssuerstring nullable
requestedScopesstring[]
identityChangedboolean required
reconnectionRequiredboolean required
nextStepstring

Changes

  • bd67819c44d2Revision changes
    • warning

      added the new provider_setup_required enum value to the ////// response property for the response status

    • warning

      added the new provider_setup_required enum value to the ////// response property for the response status

    • warning

      added the new provider_setup_required enum value to the ////// response property for the response status

    • warning

      added the new provider_setup_required enum value to the ////// response property for the response status

    • info

      added the new optional request property

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • dc19b69f67a2Revision changes
    • info

      added the optional property / to the response with the status