Create connection

Create a new MCP connection with an auto-generated ID. Requires API key and namespace ownership.

POST /connect/{namespace}

Create connection

cURL

curl --request POST \
  --url https://api.smithery.ai/connect/{namespace} \
  --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,
    "scenario": "A developer inbox with 3 unread Q4 planning threads."
  }
}
'

201

{
  "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

Body

application/json

transport · enum<string>

Connection transport. Use uplink for a local server paired over Smithery CLI.

Available options: http, uplink

Example:

"http"

mcpUrl · string<uri>

URL of the MCP server. Required for HTTP connections. Omit for uplink connections.

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. Tool calls are LLM-simulated against the registry's scanned schemas and never reach the upstream server. Provide an optional scenario to seed the simulator with a starting-state description. Registry servers only; frozen at creation (cannot be toggled via PUT).

Show child attributes

Example:

{
  "enabled": true,
  "scenario": "A developer inbox with 3 unread Q4 planning threads."
}

Response

201

application/json

Connection created

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