Create connection

POST

connect

{namespace}

Create connection

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",
  "server": "upstash/context7-mcp",
  "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."
  }
}
'

import requests

url = "https://api.smithery.ai/connect/{namespace}"

payload = {
    "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,
        "scenario": "A developer inbox with 3 unread Q4 planning threads."
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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,
      scenario: 'A developer inbox with 3 unread Q4 planning threads.'
    }
  })
};

fetch('https://api.smithery.ai/connect/{namespace}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.smithery.ai/connect/{namespace}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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,
        'scenario' => 'A developer inbox with 3 unread Q4 planning threads.'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.smithery.ai/connect/{namespace}"

	payload := strings.NewReader("{\n  \"transport\": \"http\",\n  \"mcpUrl\": \"https://mcp.example.com/sse\",\n  \"server\": \"upstash/context7-mcp\",\n  \"name\": \"My MCP Server\",\n  \"metadata\": {\n    \"userId\": \"user123\",\n    \"team\": \"engineering\"\n  },\n  \"headers\": {\n    \"X-API-Key\": \"secret-key\"\n  },\n  \"mock\": {\n    \"enabled\": true,\n    \"scenario\": \"A developer inbox with 3 unread Q4 planning threads.\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.smithery.ai/connect/{namespace}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"transport\": \"http\",\n  \"mcpUrl\": \"https://mcp.example.com/sse\",\n  \"server\": \"upstash/context7-mcp\",\n  \"name\": \"My MCP Server\",\n  \"metadata\": {\n    \"userId\": \"user123\",\n    \"team\": \"engineering\"\n  },\n  \"headers\": {\n    \"X-API-Key\": \"secret-key\"\n  },\n  \"mock\": {\n    \"enabled\": true,\n    \"scenario\": \"A developer inbox with 3 unread Q4 planning threads.\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.smithery.ai/connect/{namespace}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"transport\": \"http\",\n  \"mcpUrl\": \"https://mcp.example.com/sse\",\n  \"server\": \"upstash/context7-mcp\",\n  \"name\": \"My MCP Server\",\n  \"metadata\": {\n    \"userId\": \"user123\",\n    \"team\": \"engineering\"\n  },\n  \"headers\": {\n    \"X-API-Key\": \"secret-key\"\n  },\n  \"mock\": {\n    \"enabled\": true,\n    \"scenario\": \"A developer inbox with 3 unread Q4 planning threads.\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": "<string>",
  "message": "Invalid request"
}

{
  "error": "not_found",
  "message": "Resource not found"
}

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 a custom MCP server. For Smithery registry servers, prefer server.

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

Show child attributes

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

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 | null

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

List triggersList trigger types exposed by a connection.

⌘I

Create connection

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",
  "server": "upstash/context7-mcp",
  "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."
  }
}
'

import requests

url = "https://api.smithery.ai/connect/{namespace}"

payload = {
    "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,
        "scenario": "A developer inbox with 3 unread Q4 planning threads."
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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,
      scenario: 'A developer inbox with 3 unread Q4 planning threads.'
    }
  })
};

fetch('https://api.smithery.ai/connect/{namespace}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.smithery.ai/connect/{namespace}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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,
        'scenario' => 'A developer inbox with 3 unread Q4 planning threads.'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.smithery.ai/connect/{namespace}"

	payload := strings.NewReader("{\n  \"transport\": \"http\",\n  \"mcpUrl\": \"https://mcp.example.com/sse\",\n  \"server\": \"upstash/context7-mcp\",\n  \"name\": \"My MCP Server\",\n  \"metadata\": {\n    \"userId\": \"user123\",\n    \"team\": \"engineering\"\n  },\n  \"headers\": {\n    \"X-API-Key\": \"secret-key\"\n  },\n  \"mock\": {\n    \"enabled\": true,\n    \"scenario\": \"A developer inbox with 3 unread Q4 planning threads.\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.smithery.ai/connect/{namespace}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"transport\": \"http\",\n  \"mcpUrl\": \"https://mcp.example.com/sse\",\n  \"server\": \"upstash/context7-mcp\",\n  \"name\": \"My MCP Server\",\n  \"metadata\": {\n    \"userId\": \"user123\",\n    \"team\": \"engineering\"\n  },\n  \"headers\": {\n    \"X-API-Key\": \"secret-key\"\n  },\n  \"mock\": {\n    \"enabled\": true,\n    \"scenario\": \"A developer inbox with 3 unread Q4 planning threads.\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.smithery.ai/connect/{namespace}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"transport\": \"http\",\n  \"mcpUrl\": \"https://mcp.example.com/sse\",\n  \"server\": \"upstash/context7-mcp\",\n  \"name\": \"My MCP Server\",\n  \"metadata\": {\n    \"userId\": \"user123\",\n    \"team\": \"engineering\"\n  },\n  \"headers\": {\n    \"X-API-Key\": \"secret-key\"\n  },\n  \"mock\": {\n    \"enabled\": true,\n    \"scenario\": \"A developer inbox with 3 unread Q4 planning threads.\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": "<string>",
  "message": "Invalid request"
}

{
  "error": "not_found",
  "message": "Resource not found"
}

Welcome

Connect

Publish

Integrations

Concepts

Cookbooks

API Reference

Authorizations

Path Parameters

Body

Response