---
title: "Edit an External MCP Connection"
method: PUT
path: "/v1/mcp-connections/{connectionId}"
tags: ["Authentication"]
---

# Edit an External MCP Connection

`PUT /v1/mcp-connections/{connectionId}`

Workspace owners and super-admins can edit any connection. Other org members can edit only connections they created. Name and direct access changes preserve credentials. URL, authentication type, or credential-mode changes invalidate the old identity atomically. Secret fields are write-only optional replacements and are never returned. expectedUpdatedAt prevents stale edits.

## Path parameters

- `connectionId` string, typeid, required

## Request body

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

## Response `200`

Connection updated.

- ExternalMcpConnectionUpdatedResponse
  - `id` string, required
  - `name` string, required
  - `url` string, required
  - `authType` 'oauth' | 'apikey' | 'none', required
  - `credentialMode` 'shared' | 'per_member', 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

- `400` — Invalid request.
- `401` — The caller must be signed in.
- `403` — Only workspace owners, super-admins, or the connection creator can edit MCP connections.
- `404` — Unknown connection.
- `409` — The edit is stale or changes marketplace-owned identity fields.
- `502` — The proposed API-key or no-auth configuration could not be validated.

---

[API](https://skmtc.net/openworklabs/apis/den-api.md) · [All operations](https://skmtc.net/openworklabs/apis/den-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openworklabs/den-api/versions/805150503452/schema)