---
title: "Register a new External MCP Connection for the org"
method: POST
path: "/v1/mcp-connections"
tags: ["Capability Sources"]
---

# Register a new External MCP Connection for the org

`POST /v1/mcp-connections`

Admin-only. Registers a third-party MCP server by name + URL and grants access (org-wide, teams, or members). Use GET /v1/mcp-connections/presets for known server URLs (Notion, Linear, Stripe, Sentry, Slack, Context7). For credentialMode per_member, each member connects their own account afterwards — share links.yourConnections from the response so teammates know where to sign in. For servers with pre-registered OAuth apps, whitelist links.oauthCallback. API-key and OAuth-client credentials cannot be created through the agent surface; use the dashboard.

## Request body

- union
  - object
    - `kind` 'native_provider', required
    - `nativeProviderKey` string, required
    - `name` string, required
    - `oauthClient` object, required
      - `clientId` string, required
      - `clientSecret` string
      - `features` string[]
  - object
    - `kind` 'external_mcp'
    - `name` string, required
    - `url` string, uri, required
    - `authType` 'oauth' | 'apikey' | 'none', required
    - `credentialMode` 'shared' | 'per_member'
    - `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 created.

- ExternalMcpConnectionCreatedResponse
  - `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
  - `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[]
    - `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[]
  - `links` object, required
    - `yourConnections` string, required
    - `oauthCallback` string, required

## Other responses

- `400` — Invalid request.
- `401` — The caller must be signed in.
- `403` — Only workspace owners and admins can add MCP connections.
- `502` — The upstream MCP server could not be reached.

---

[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)