Skip to main content
Deep links provide a seamless way to integrate Smithery MCPs into supported clients. When a user clicks a deep link from our server page, the client automatically configures the MCP with the correct settings. To get started with integration, please contact us at [email protected] or join our Discord community for support. Magic Link Integration Flow

​
Protocol Specification

Deep links use the following URL format: 
`${clientScheme}://{optionalDeepLinkHandler}/mcp/install?name=${encodeURIComponent(displayName)}&config=${encodeURIComponent(config)}`

// Example:
// cursor://anysphere.cursor-deeplink/mcp/install?<server-display-name>&<base64-encoded-json-config>
ComponentDescription
{client-schema}://Protocol scheme
{optional-handler}Deeplink handler
/mcp/installPath
nameQuery parameter for the server name
configQuery parameter for base64 encoded JSON configuration
The config parameter contains a URL-encoded JSON object with the following schema: 
interface StdioMCPConfig {
  type: "stdio";
  command: string; // Example: "npx"
  args: string[];  // Command line arguments for the MCP CLI
}

// Note: The configuration does not require an "env" field because
// Smithery automatically handles sensitive data through saved configurations.

interface HttpMCPConfig {
  type: "http";
  url: string;    // URL of the MCP server
}

type MCPConfig = StdioMCPConfig | HttpMCPConfig;
The configuration fields are detailed in the table below:
FieldDescriptionExample
typeServer connection type"stdio" or "http"
commandCommand to start the server executable (required for stdio type). The command needs to be available on your system path or contain its full path."npx"
argsArray of arguments passed to the command (required for stdio type).["-y", "@smithery/cli@latest", "run", "@wonderwhy-er/desktop-commander"]
urlURL of the MCP server (required for http type)"https://server.smithery.ai/exa"

​
Example Configurations

​
stdio-based Configuration:

{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@smithery/cli@latest", "run", "@wonderwhy-er/desktop-commander"]
}

​
HTTP-based Configuration:

{
  "type": "http",
  "url": "https://server.smithery.ai/exa"
}
When your client receives a deeplink:
  1. Parse the URL-encoded config parameter using decodeURIComponent
  2. Parse the resulting string as JSON
  3. Create the transport with provided arguments
Example implementation: 
// Parse deeplink and return name and config
function handleDeepLink(url: string) {
  const urlObj = new URL(url)
  const name = urlObj.searchParams.get('name')
  const config = JSON.parse(decodeURIComponent(urlObj.searchParams.get('config')))
  return { config, name }
}

​
Stdio Example

// Example with stdio transport
async function setupStdioMCP(url: string) {
  const config = handleDeepLink(url)
  const transport = new StdioClientTransport({
    command: config.command,
    args: config.args
  })
  
  const client = new Client({ name: "Test client" })
  await client.connect(transport)
  return client
}

​
HTTP Example

// Example with HTTP transport
async function setupHttpMCP(url: string) {
  const config = handleDeepLink(url)
  const transport = new StreamableHTTPClientTransport(config.url)
  
  const client = new Client({ name: "Test client" })
  await client.connect(transport)
  return client
}