Registry API

The Smithery Registry API provides a programmatic way to search and obtain launch configurations for Model Context Protocol (MCP) servers. This documentation will walk you through using the Registry API to obtain a remote MCP server and connect to it.

Note: Smithery is still in early stages of development and the API may change in the future.

Concepts

Smithery Registry contains an index of MCP servers. Every server may have different ways of launching or connecting to them. Server authors specify a configuration schema, which is a JSON schema that defines the structure of the configuration that is required to connect to the server.

Authentication

All endpoints require authentication via a bearer token. You can create an API key by clicking on your login icon, and selecting API keys in the dropdown menu.

Include the following header in your API requests:

headers: {
'Authorization': 'Bearer your-api-token'
}

List Servers

GET https://registry.smithery.ai/servers

Retrieves a paginated list of all available servers.

Query Parameters

• q (optional): Search query. We use semantic search, so treat this as a prompt.
• page (optional): Page number for pagination (default: 1)
• pageSize (optional): Number of items per page (default: 10)

Filtering

• Text Search: Simply type any text to search semantically (e.g., machine learning)
• Owner Filter: Use owner:username to filter by repository owner (e.g., owner:smithery-ai)
• Repository Filter: Use repo:repository-name to filter by repository name (e.g., repo:fetch)
• Deployment Status: Use is:deployed to show only deployed servers

You can combine multiple filters together. For example:

owner:smithery-ai repo:fetch is:deployed machine learning

Response

{
  servers: Array<{
    qualifiedName: string;
    displayName: string;
    description: string;
    // Link to Smithery server page
    homepage: string;
    // Number of times the server has been used via tool calling
    useCount: string;
    // True if this server is deployed on Smithery as a HTTP server
    isDeployed: boolean
    createdAt: string;
  }>;
  pagination: {
    currentPage: number;
    pageSize: number;
    totalPages: number;
    totalCount: number;
};
}

The response includes basic information about each server and pagination details to help you navigate through the list of servers.

Get Server

GET https://registry.smithery.ai/servers/{qualifiedName}

Retrieves information about a specific server by its qualified name. The qualified name is a unique human-readable identifier for the server. You can find the qualified name from the server page's url: https://smithery.ai/server/{qualifiedName}.

Response

{
  qualifiedName: string;
  displayName: string;
  deploymentUrl: string;
  connections: Array<{
    type: string;
    url?: string;
    configSchema: JSONSchema;
  }>;
  security: {
    scanPassed: boolean;
  } | null;
}

We will return you a response containing information about the server, including its qualified name, display name, connection details, and security scan status.

The connection details specify how you can connect to this server.

• type: The type of connection, such as "http" for MCP served over streamable HTTP.
• url: The URL to connect to.
• connections: A list of possible ways to connect to the server.
  • type: Either stdio or http (streamable HTTP).
  • url: The HTTP URL to connect to, if applicable.
  • configSchema: The JSON schema for the server's configuration. You must specify a config that complies with this schema in order to connect to this server. Some servers will have no configuration required.
• security: Information about the server's security status (recently added feature)
  • scanPassed: A boolean indicating whether the server has passed security checks. Currently we use Invariant to scan the server for tool poisoning, rug pulls, cross origins escalations and prompt injection attacks. This field will be null if no security scan has been performed yet.

Connecting to Remote Servers

To connect to remote servers, you have to format your URL as such:

https://server.smithery.ai/${qualifiedName}/mcp?config=${base64_encoded_config}&api_key=${smithery_api_key}

Here's an example for constructing the URL with the required parameters:

import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"

// Create server URL
const serverUrl = new URL("https://server.smithery.ai/{qualifiedName}/mcp")

// Prepare config
const config = {
// Your config object that matches the server's configSchema
}
const configString = JSON.stringify(config)

// Add config and API key to URL
// btoa() converts the JSON string to base64 for safe URL transmission
serverUrl.searchParams.set("config", btoa(configString))
serverUrl.searchParams.set("api_key", "your-smithery-api-key")

// Create transport with the configured URL
const transport = new StreamableHTTPClientTransport(serverUrl)