Create or update connection

Create or update an MCP connection with the given ID. mcpUrl is required when creating a new connection, but optional when updating. 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.

PUT /connect/{namespace}/{connectionId}

Create or update connection

cURL

curl --request PUT \
  --url https://api.smithery.ai/connect/{namespace}/{connectionId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transport": "http",
  "mcpUrl": "https://mcp.example.com/sse",
  "name": "My MCP Server",
  "metadata": {
    "userId": "user123",
    "team": "engineering"
  },
  "headers": {
    "X-API-Key": "secret-key"
  },
  "mock": {
    "enabled": true
  }
}
'

200

{
  "connectionId": "clever-dolphin-a9X3",
  "name": "<string>",
  "mcpUrl": "<string>",
  "metadata": {},
  "transport": "http",
  "mock": {
    "enabled": true,
    "scenario": "Slack workspace with an active #community-ops channel containing recent event-planning messages, plus 50 Airtable candidate records with mixed tenure and interests."
  },
  "iconUrl": "<string>",
  "createdAt": "<string>",
  "status": {
    "state": "<string>"
  },
  "serverInfo": {
    "name": "<string>",
    "version": "<string>",
    "title": "<string>",
    "icons": [
      {
        "src": "<string>",
        "mimeType": "<string>",
        "sizes": [
          "<string>"
        ],
        "theme": "light"
      }
    ],
    "websiteUrl": "<string>",
    "description": "<string>"
  }
}

Authorizations

Authorization · string · header · required

Smithery API key as Bearer token

Path Parameters

namespace · string · required

connectionId · string · required

Body

application/json

transport · enum<string>

Connection transport. Defaults to the existing connection transport when updating.

Available options: http, uplink

Example:

"http"

mcpUrl · string<uri>

URL of the MCP server. Required when creating a new connection. Optional when updating — omit to keep the existing URL.

Example:

"https://mcp.example.com/sse"

name · string

Human-readable name (optional, defaults to connection ID)

Required string length: 1 - 255

Example:

"My MCP Server"

metadata · object

Custom metadata for filtering connections

Show child attributes

Example:

{
  "userId": "user123",
  "team": "engineering"
}

headers · object

Custom headers to send with MCP requests (stored securely, not returned in responses)

Show child attributes

Example:

{ "X-API-Key": "secret-key" }

mock · object

Run this connection in mock mode. Only honored on first creation; ignored on updates to an existing connection.

Show child attributes

Example:

{ "enabled": true }

Response

200

application/json

Connection updated

connectionId · string · required

Connection ID (auto-generated or developer-defined)

Example:

"clever-dolphin-a9X3"

name · string · required

Human-readable name

mcpUrl · string | null · required

MCP server URL. Null for uplink connections.

metadata · object · required

Show child attributes

transport · enum<string>

Connection transport

Available options: http, uplink

mock · object

Mock-mode config: {enabled: true, scenario?} when LLM-simulated, absent otherwise.

Show child attributes

iconUrl · string | null

createdAt · string

ISO 8601 timestamp

status · ConnectionStatusConnected · object

Last known connection status

ConnectionStatusConnected

ConnectionStatusDisconnected

ConnectionStatusAuthRequired

ConnectionStatusInputRequired

ConnectionStatusError

Show child attributes

serverInfo · object

Server information from MCP initialization (name, version)

Show child attributes