Skip to main content
PUT
/
connect
/
{namespace}
/
{connectionId}
Create or update connection
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",
  "server": "upstash/context7-mcp",
  "name": "My MCP Server",
  "metadata": {
    "userId": "user123",
    "team": "engineering"
  },
  "headers": {
    "X-API-Key": "secret-key"
  },
  "mock": {
    "enabled": true
  }
}
'
{
  "connectionId": "clever-dolphin-a9X3",
  "name": "<string>",
  "mcpUrl": "<string>",
  "metadata": {},
  "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>"
        ]
      }
    ],
    "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 a custom MCP server. For Smithery registry servers, prefer server. Required with server omitted when creating a new HTTP connection; optional when updating.

Example:

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

​
server
string

Smithery registry server qualified name. Use this instead of mcpUrl for registry servers.

Required string length: 1 - 255
Pattern: ^@?[a-zA-Z0-9][a-zA-Z0-9_-]*(?:\/[a-zA-Z0-9][a-zA-Z0-9_-]*)?$
Example:

"upstash/context7-mcp"

​
source
object
​
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

Example:
{
  "userId": "user123",
  "team": "engineering"
}
​
headers
object

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

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.

Example:
{ "enabled": true }

Response

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
​
transport
enum<string>

Connection transport

Available options:
http,
uplink
​
mock
object

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

​
iconUrl
string | null
​
createdAt
string

ISO 8601 timestamp

​
status
ConnectionStatusConnected · object

Last known connection status

​
serverInfo
object

Server information from MCP initialization (name, version)