Skip to main content
PUT
Create or replace an External MCP Connection by stable key

Authorizations

x-api-key
string
header
required

Organization API key passed as the x-api-key header. The raw key is the header value; do not prefix it with Bearer.

Headers

If-Match
string<date-time>

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

Path Parameters

externalKey
string
required

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

Pattern: ^[a-z0-9][a-z0-9._-]{0,127}$

Body

application/json
name
string
required
Required string length: 1 - 255
url
string<uri>
required
Maximum string length: 2048
authType
enum<string>
required
Available options:
oauth,
apikey,
none
kind
string
Allowed value: "external_mcp"
credentialMode
enum<string>
default:shared
Available options:
shared,
per_member
exposeDirectly
boolean
default:false
apiKey
string
Required string length: 1 - 4096
apiKeyAuthScheme
enum<string>
Available options:
bearer,
token
requestHeaders
object[]

Sent with every request to the MCP server alongside OpenWork's own sign-in. Values are stored encrypted and never returned. Up to four.

Maximum array length: 4
oauthClient
object
manualOAuthEndpoints
object | null

Administrator-pinned authorization and token URLs. Both required; null restores strict discovery. Changing them clears saved sign-ins.

authorizationServerIssuer
string<uri> | null
Maximum string length: 2048
requestedScopes
string[]
Maximum array length: 512
Required string length: 1 - 255
requestSelectedScopesOnly
boolean

When true, sign-in asks for requestedScopes alone, leaving out any others the server's sign-in challenge names. Needs at least one requested scope. People who already signed in keep their current access until they sign in again.

access
object

Response

Connection updated.

id
string
required
name
string
required
externalKey
string | null
required
url
string
required
authType
enum<string>
required
Available options:
oauth,
apikey,
none
credentialMode
enum<string>
required
Available options:
shared,
per_member
apiKeyAuthScheme
enum<string>
required
Available options:
bearer,
token
requestHeaderNames
string[]
required
exposeDirectly
boolean
required
connected
boolean
required
connectedAt
string<date-time> | null
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
updatedAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
connectedForMe
boolean
required
requiredBy
object[]
required
identityManagedBy
object[]
required
access
object | null
required
identityChanged
boolean
required
reconnectionRequired
boolean
required
readiness
object | null

The calling member's own last check. Null means never checked for them (or the settings or their sign-in changed since).

organizationReadiness
object | null

scope=manageable only. Whether the connector itself works: for shared connections the shared credential's check; for per-member connections the latest Ready check any member recorded for the current settings, otherwise the caller's own check. Null means nobody has checked it yet.

mcpUrl
string<uri>
createdByName
string | null
createdByYou
boolean
createdByOrgMembershipId
string | null
canRemove
boolean
createdAt
string<date-time>
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
needsReconnect
boolean
credentialHealth
enum<string>
Available options:
unknown,
ready,
reconnect_required
credentialHealthReason
enum<string> | null
Available options:
authorization_rejected,
credential_expired,
post_authorization_validation_failed
credentialHealthCheckedAt
string<date-time> | null
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
issuerReviewRequired
boolean
reconnectActionOwner
enum<string> | null
Available options:
member,
organization_admin
missingFeatures
string[]
externalAccountId
string | null
grantedScopes
string[]
tenantId
string | null
requiredAuthType
enum<string> | null
Available options:
oauth,
apikey,
none
authPolicyConfirmed
boolean
authTypeMismatch
boolean
oauthClientConfigured
boolean
oauthClientRequired
boolean
setupRequired
boolean
oauthClientId
string | null
oauthClientHasSecret
boolean

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

manualOAuthEndpoints
object | null

Only returned with explicit connection-settings view permission; omitted from usable member listings, including for the connection creator.

oauthCallbackUrl
string | null
oauthSharedCallbackUrl
string | null
oauthClientMetadataUrl
string | null
oauthCallbackMode
enum<string> | null
Available options:
shared-v1,
isolated-v1,
legacy-v1
oauthRegistrationSource
enum<string> | null
Available options:
pre-registered,
client-metadata,
dynamic
authorizationServerIssuer
string | null
requestedScopes
string[]
requestSelectedScopesOnly
boolean

Whether sign-in asks for requestedScopes alone, leaving out any others the server's sign-in challenge names.

credentialPrompt
object
nextStep
string