---
title: "Create or update connection"
method: PUT
path: "/connect/{namespace}/{connectionId}"
tags: ["connect"]
---

# Create or update connection

`PUT /connect/{namespace}/{connectionId}`

Create or update an MCP connection with the given ID. mcpUrl is required when creating a new connection, but optional when updating (omit to keep the existing URL). Returns 409 if a different mcpUrl is provided, except while the connection is input_required and the new URL keeps the same host and path. Requires API key and namespace ownership.

## Path parameters

- `namespace` string, required
- `connectionId` string, required

## Request body

- UpsertConnectionRequest
  - `mcpUrl` string, uri — URL of the MCP server. Required when creating a new connection. Optional when updating — omit to keep the existing URL.
  - `name` string — Human-readable name (optional, defaults to connection ID)
  - `metadata` object — Custom metadata for filtering connections
  - `headers` object — Custom headers to send with MCP requests (stored securely, not returned in responses)

## Response `200`

Connection updated

- Connection
  - `connectionId` string, required — Connection ID (auto-generated or developer-defined)
  - `name` string, required — Human-readable name
  - `mcpUrl` string, required — MCP server URL
  - `metadata` object, nullable, required
  - `iconUrl` string, nullable
  - `createdAt` string — ISO 8601 timestamp
  - `status` union
    - object
      - `state` 'connected', required
    - object
      - `state` 'auth_required', required
      - `authorizationUrl` string, uri — URL to redirect user for OAuth authorization
    - object
      - `state` 'input_required', required
      - `http` CredentialProfileHttp, required
        - `headers` object
        - `query` object
      - `missing` object, required
        - `headers` string[], required
        - `query` string[], required
    - object
      - `state` 'error', required
      - `message` string, required — Error message
  - `serverInfo` ServerInfo
    - `name` string, required
    - `title` string
    - `icons` object[]
      - `src` string, required
      - `mimeType` string
      - `sizes` string[]
      - `theme` 'light' | 'dark'
    - `version` string, required
    - `websiteUrl` string
    - `description` string

## Other responses

- `201` — Connection created
- `400` — Validation error
- `404` — Namespace not found or access denied
- `409` — URL mismatch - cannot change mcpUrl outside input_required same-host same-path updates

## Changes

- **2026-04-12** `01f97a60fd96` — 2 breaking
  - added `subschema #3: ConnectionStatusInputRequired` to the `status` response property `oneOf` list for the response status `200`
  - added `subschema #3: ConnectionStatusInputRequired` to the `status` response property `oneOf` list for the response status `201`
- **2026-04-09** `ca0e2e65019d` — 1 warning
  - removed the request property `unstableCallbackUrl`
- **2026-02-19** `769d63b5f171` — 1 info
  - added the new optional request property `unstableCallbackUrl`
- **2026-02-13** `eab7f6413d3a` — 1 info
  - the request property `mcpUrl` became optional
- **2026-02-04** `0ea2d8e23fa1` — 1 info
  - added the success response with the status `200`

[Change history](https://skmtc.dev/smithery-ai/apis/smithery-platform-api/changes/connect/:namespace/:connectionId/put.md)

---

[API](https://skmtc.dev/smithery-ai/apis/smithery-platform-api.md) · [All operations](https://skmtc.dev/smithery-ai/apis/smithery-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/smithery-ai/apis/smithery-platform-api/revisions/01f97a60fd96?raw)