---
title: "Create or replace an External MCP Connection by stable key"
method: PUT
path: "/v1/mcp-connections/by-key/{externalKey}"
tags: ["Capability Sources"]
---

# Create or replace an External MCP Connection by stable key

`PUT /v1/mcp-connections/by-key/{externalKey}`

Admin-only declarative upsert. Creates a connection when the organization has not used the key, otherwise replaces the keyed connection without changing its stable identity.

## Path parameters

- `externalKey` string, required

## Headers

- `If-Match` string, date-time

## Request body

- ExternalMcpConnectionByKeyUpsertInput
  - `kind` 'external_mcp'
  - `name` string, required
  - `url` string, uri, required
  - `authType` 'oauth' | 'apikey' | 'none', required
  - `credentialMode` 'shared' | 'per_member'
  - `exposeDirectly` boolean
  - `apiKey` string
  - `oauthClient` object
    - `clientId` string, required
    - `clientSecret` string
    - `tokenEndpointAuthMethod` 'client_secret_basic' | 'client_secret_post'
  - `authorizationServerIssuer` string, uri, nullable
  - `requestedScopes` string[]
  - `access` ExternalMcpConnectionAccessInput
    - `orgWide` boolean
    - `memberIds` string[]
    - `teamIds` string[]

## Response `200`

Connection updated.

- ExternalMcpConnectionUpdatedResponse
  - `id` string, required
  - `name` string, required
  - `externalKey` string, nullable, required
  - `url` string, required
  - `authType` 'oauth' | 'apikey' | 'none', required
  - `credentialMode` 'shared' | 'per_member', required
  - `exposeDirectly` boolean, required
  - `connected` boolean, required
  - `connectedAt` string, nullable, required
  - `createdByName` string, nullable
  - `updatedAt` string, date-time, required
  - `connectedForMe` boolean, required
  - `needsReconnect` boolean
  - `credentialHealth` 'unknown' | 'ready' | 'reconnect_required'
  - `credentialHealthReason` 'authorization_rejected' | 'credential_expired' | 'post_authorization_validation_failed', nullable
  - `credentialHealthCheckedAt` string, date-time, nullable
  - `issuerReviewRequired` boolean
  - `reconnectActionOwner` 'member' | 'organization_admin', nullable
  - `missingFeatures` string[]
  - `externalAccountId` string, nullable
  - `grantedScopes` string[]
  - `tenantId` string, nullable
  - `requiredBy` ExternalMcpConnectionRequiredBy[], required
    - `pluginId` string, required
    - `name` string, required
  - `identityManagedBy` ExternalMcpConnectionRequiredBy[], required
    - `pluginId` string, required
    - `name` string, required
  - `requiredAuthType` 'oauth' | 'apikey' | 'none', nullable
  - `authPolicyConfirmed` boolean
  - `authTypeMismatch` boolean
  - `oauthClientConfigured` boolean
  - `oauthClientRequired` boolean
  - `setupRequired` boolean
  - `access` ExternalMcpConnectionAccessSummary, required
    - `orgWide` boolean, required
    - `memberIds` string[], required
    - `teamIds` string[], required
  - `oauthClientId` string, nullable
  - `oauthCallbackUrl` string, nullable
  - `oauthSharedCallbackUrl` string, nullable
  - `oauthClientMetadataUrl` string, nullable
  - `oauthCallbackMode` 'shared-v1' | 'isolated-v1' | 'legacy-v1', nullable
  - `oauthRegistrationSource` 'pre-registered' | 'client-metadata' | 'dynamic', nullable
  - `authorizationServerIssuer` string, nullable
  - `requestedScopes` string[]
  - `identityChanged` boolean, required
  - `reconnectionRequired` boolean, required

## Other responses

- `201` — Connection created.
- `400` — Invalid request.
- `401` — The caller must be signed in.
- `403` — Only workspace owners and admins can upsert MCP connections.
- `409` — The edit is stale or changes marketplace-owned identity fields.
- `502` — The proposed connection could not be validated.

## Changes

- **2026-09-05** `cb34559d4b4d` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openworklabs/apis/den-api/changes/v1/mcp-connections/by-key/:externalKey/put.md)

---

[API](https://skmtc.dev/openworklabs/apis/den-api.md) · [All operations](https://skmtc.dev/openworklabs/apis/den-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openworklabs/apis/den-api/revisions/587cfbbef56c?raw)