Smithery

Smithery servers API

The servers API from Smithery — 11 operation(s) for servers.

GitHub OpenAPI

Documentation

📖
Documentation
https://smithery.ai/docs
📖
Documentation
https://smithery.ai/docs/usage/connect

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/smithery-ai/refs/heads/main/openapi/smithery-ai-servers-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/smithery-ai/refs/heads/main/json-schema/smithery-server-schema.json
📊
JSONStructure
https://raw.githubusercontent.com/api-evangelist/smithery-ai/refs/heads/main/json-structure/smithery-server-structure.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/smithery-ai/refs/heads/main/json-schema/smithery-connection-schema.json
📊
JSONStructure
https://raw.githubusercontent.com/api-evangelist/smithery-ai/refs/heads/main/json-structure/smithery-connection-structure.json

Other Resources

🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/smithery-ai/refs/heads/main/json-ld/smithery-ai-context.jsonld
🔗
Vocabulary
https://raw.githubusercontent.com/api-evangelist/smithery-ai/refs/heads/main/vocabulary/smithery-ai-vocabulary.yml
🔗
Spectral
https://raw.githubusercontent.com/api-evangelist/smithery-ai/refs/heads/main/rules/smithery-ai-rules.yml

OpenAPI Specification

smithery-ai-servers-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Smithery connect servers API
  version: 1.0.0
  description: Connect to MCP servers hosted on Smithery without managing OAuth, credentials, or sessions. Create stateless connections to any MCP server, execute MCP JSON-RPC, list/call tools and triggers, and manage subscriptions for trigger events.
servers:
- url: https://api.smithery.ai
tags:
- name: servers
paths:
  /servers/{qualifiedName}:
    get:
      operationId: getServers:namespace
      tags:
      - servers
      summary: Get a server
      description: Retrieve server details including connections, tools, and security status.
      responses:
        '200':
          description: Server found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Server'
        '404':
          description: Server or namespace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryError'
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
    put:
      operationId: putServers:namespace
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                displayName:
                  example: My Server
                  type: string
                description:
                  example: A simple server
                  type: string
              id: CreateNamespaceServerRequest
      tags:
      - servers
      summary: Create a server
      description: Create a new server. Idempotent — returns success if the server already exists and is owned by the caller.
      responses:
        '201':
          description: Server created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  namespace:
                    type: string
                    example: myorg
                  server:
                    type: string
                    example: ''
                  displayName:
                    type: string
                    example: My Server
                  description:
                    type: string
                    example: A simple server
                  createdAt:
                    type: string
                    example: '2024-01-01T00:00:00.000Z'
                required:
                - namespace
                - server
                - displayName
                - description
                - createdAt
                id: CreateNamespaceServerResponse
        '400':
          description: Bad request (invalid name format)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryError'
        '403':
          description: Forbidden (namespace not owned by user or missing servers:write permission)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryError'
        '404':
          description: Namespace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryError'
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
    patch:
      operationId: patchServers:namespace
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                displayName:
                  type: string
                description:
                  type: string
                homepage:
                  anyOf:
                  - type: string
                  - type: 'null'
                repositoryUrl:
                  anyOf:
                  - type: string
                  - type: 'null'
                backlinkUrl:
                  anyOf:
                  - type: string
                  - type: 'null'
                license:
                  anyOf:
                  - type: string
                  - type: 'null'
                iconUrl:
                  anyOf:
                  - type: string
                  - type: 'null'
                unlisted:
                  type: boolean
              id: UpdateServerRequest
      tags:
      - servers
      summary: Update a server
      description: Update server metadata such as display name, description, repository, icon, or visibility.
      responses:
        '200':
          description: Server updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  namespace:
                    type: string
                  server:
                    type: string
                required:
                - success
                - namespace
                - server
                id: UpdateServerResponse
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryError'
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryError'
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
    delete:
      operationId: deleteServers:namespace
      tags:
      - servers
      summary: Delete a server
      description: Permanently delete a server, its releases, and associated resources.
      responses:
        '200':
          description: Server deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  namespace:
                    type: string
                  server:
                    type: string
                required:
                - success
                - namespace
                - server
                id: DeleteSuccess
        '404':
          description: Server not found or not owned by user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistryError'
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
  /servers/{qualifiedName}/download:
    get:
      operationId: getServers:namespaceDownload
      tags:
      - servers
      summary: Download server bundle
      description: Download the MCPB bundle for the latest successful stdio release.
      responses:
        '200':
          description: Bundle file
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '404':
          description: Bundle not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
                id: BundleDownloadError
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
  /servers/{qualifiedName}/releases:
    put:
      operationId: putServers:namespaceReleases
      tags:
      - servers
      summary: Publish a server
      description: Submit a release via multipart form. Supports hosted (JS module upload), external (URL), and stdio (MCPB bundle) release types.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                payload:
                  type: string
                  description: JSON-encoded release payload. See DeployPayload schema for structure.
                module:
                  type: string
                  format: binary
                  description: JavaScript module file (for hosted releases)
                sourcemap:
                  type: string
                  format: binary
                  description: Source map file (for hosted releases)
                bundle:
                  type: string
                  format: binary
                  description: MCPB bundle file (for stdio releases)
              required:
              - payload
      responses:
        '202':
          description: Release accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeployResponse'
        '400':
          description: Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentError'
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
    get:
      operationId: getServers:namespaceReleases
      parameters:
      - in: query
        name: page
        schema:
          default: 1
          type: integer
          minimum: 1
          maximum: 9007199254740991
      - in: query
        name: pageSize
        schema:
          default: 20
          type: integer
          minimum: 1
          maximum: 100
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
      tags:
      - servers
      summary: List releases
      description: List releases ordered by most recent first. Logs are omitted — fetch a specific release to see logs.
      responses:
        '200':
          description: Paginated list of releases
          content:
            application/json:
              schema:
                type: object
                properties:
                  releases:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        status:
                          type: string
                          description: 'Current status: QUEUED, WORKING, SUCCESS, FAILURE, FAILURE_SCAN, AUTH_REQUIRED, CANCELLED, or INTERNAL_ERROR.'
                        type:
                          type: string
                          description: 'Release type: hosted_shttp (Smithery-hosted), external_shttp (external URL), or stdio (local binary).'
                        commit:
                          description: Git commit SHA that triggered this release.
                          anyOf:
                          - type: string
                          - type: 'null'
                        commitMessage:
                          description: Git commit message associated with this release.
                          anyOf:
                          - type: string
                          - type: 'null'
                        branch:
                          description: Git branch this release was built from.
                          anyOf:
                          - type: string
                          - type: 'null'
                        upstreamUrl:
                          description: Upstream MCP server URL. Present only for external releases.
                          anyOf:
                          - type: string
                          - type: 'null'
                        mcpUrl:
                          description: The MCP endpoint URL for connecting to this server.
                          type: string
                          format: uri
                        createdAt:
                          type: string
                          description: ISO 8601 timestamp of when the release was created.
                        updatedAt:
                          type: string
                          description: ISO 8601 timestamp of the last status change.
                      required:
                      - id
                      - status
                      - type
                      - createdAt
                      - updatedAt
                  pagination:
                    type: object
                    properties:
                      currentPage:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      pageSize:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      totalPages:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      totalCount:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                    required:
                    - currentPage
                    - pageSize
                    - totalPages
                    - totalCount
                required:
                - releases
                - pagination
                id: DeploymentListPage
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentError'
  /servers/{qualifiedName}/releases/{id}:
    get:
      operationId: getServers:namespaceReleases:id
      tags:
      - servers
      summary: Get a release
      description: Retrieve release details including status, git metadata, pipeline logs, and MCP endpoint URL.
      responses:
        '200':
          description: Release info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentInfo'
        '404':
          description: Server or release not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentError'
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
      - schema:
          type: string
        in: path
        name: id
        required: true
  /servers/{qualifiedName}/releases/{id}/stream:
    get:
      operationId: getServers:namespaceReleases:idStream
      tags:
      - servers
      summary: Stream release logs
      description: Real-time SSE stream of release logs and status updates.
      responses:
        '200':
          description: SSE stream of release events
          content:
            text/event-stream:
              schema:
                type: string
                description: 'SSE events: init (with buffered logs), log, status, complete'
        '404':
          description: Release not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentError'
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
      - schema:
          type: string
        in: path
        name: id
        required: true
  /servers/{qualifiedName}/releases/{id}/resume:
    post:
      operationId: postServers:namespaceReleases:idResume
      tags:
      - servers
      summary: Resume a release
      description: Resume a paused release (e.g. after OAuth authorization). Use id='latest' to resume the most recent one.
      responses:
        '202':
          description: Resume accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeResponse'
        '400':
          description: Release not in resumable state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentError'
        '404':
          description: Server or release not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentError'
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
      - schema:
          type: string
        in: path
        name: id
        required: true
  /servers/{qualifiedName}/logs:
    get:
      operationId: getServers:namespaceLogs
      tags:
      - servers
      summary: List runtime logs
      description: Fetch recent runtime logs grouped by invocation.
      responses:
        '200':
          description: Logs fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeLogsResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeLogsError'
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeLogsError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeLogsError'
      parameters:
      - in: query
        name: from
        schema:
          example: '2026-01-01T00:00:00Z'
          type: string
        description: Start of time range (ISO 8601).
      - in: query
        name: to
        schema:
          example: '2026-01-01T01:00:00Z'
          type: string
        description: End of time range (ISO 8601).
      - in: query
        name: limit
        schema:
          example: 20
          type: integer
          minimum: 1
          maximum: 100
        description: Max invocations to return. Defaults to 20.
      - in: query
        name: search
        schema:
          example: error
          type: string
        description: Text search across log messages.
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
  /servers/{qualifiedName}/secrets:
    get:
      operationId: getServers:namespaceSecrets
      tags:
      - servers
      summary: List secrets
      description: List secret names. Values are not returned.
      responses:
        '200':
          description: Secrets listed
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      example: API_KEY
                    type:
                      type: string
                      example: secret_text
                  required:
                  - name
                  - type
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Server not found
                required:
                - error
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
      x-hidden: true
    put:
      operationId: putServers:namespaceSecrets
      tags:
      - servers
      summary: Set a secret
      description: Create or update a secret value.
      responses:
        '200':
          description: Secret updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                required:
                - success
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Server not found
                required:
                - error
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                value:
                  type: string
                  minLength: 1
              required:
              - name
              - value
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
      x-hidden: true
  /servers/{qualifiedName}/secrets/{secretName}:
    delete:
      operationId: deleteServers:namespaceSecrets:secretName
      tags:
      - servers
      summary: Delete a secret
      description: Remove a secret by name.
      responses:
        '200':
          description: Secret deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                required:
                - success
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Server not found
                required:
                - error
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
      - schema:
          type: string
        in: path
        name: secretName
        required: true
      x-hidden: true
  /servers/{qualifiedName}/icon:
    put:
      operationId: putServers:namespaceIcon
      tags:
      - servers
      summary: Upload server icon
      description: 'Upload or replace the server icon. Accepts a single image file via multipart/form-data. Max 1MB. Supported formats: PNG, JPEG, GIF, SVG, WebP.'
      responses:
        '200':
          description: Icon uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  iconUrl:
                    type: string
                    example: https://icons.smithery.ai/server-id.png
                required:
                - iconUrl
                id: IconResponse
        '400':
          description: Bad request (invalid file type, too large, or no file)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: File too large
                required:
                - error
                id: IconError
        '403':
          description: Forbidden (user doesn't own server)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: File too large
                required:
                - error
                id: IconError
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: File too large
                required:
                - error
                id: IconError
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
    delete:
      operationId: deleteServers:namespaceIcon
      tags:
      - servers
      summary: Delete server icon
      description: Remove the server's icon.
      responses:
        '200':
          description: Icon deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                required:
                - success
                id: IconDeleteResponse
        '403':
          description: Forbidden (user doesn't own server)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: File too large
                required:
                - error
                id: IconError
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: File too large
                required:
                - error
                id: IconError
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
    get:
      operationId: getServers:namespaceIcon
      tags:
      - servers
      summary: Get server icon
      description: Retrieve the server's icon image. Returns the image directly with appropriate content type.
      responses:
        '200':
          description: Icon image
          content:
            image/*:
              schema:
                type: string
                format: binary
        '404':
          description: No icon found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: File too large
                required:
                - error
                id: IconError
      parameters:
      - schema:
          type: string
        in: path
        name: qualifiedName
        required: true
        description: The server's qualified name (e.g. 'namespace/server' or 'namespace' for namespace-only servers). Use %2F to encode the slash.
  /servers:
    get:
      operationId: getServers
      tags:
      - servers
      summary: List all servers
      description: Search and browse public MCP servers in the Smithery registry. Supports full-text and semantic search via the `q` parameter, and filtering by deployment status, verification, ownership, and more.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServersListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServersListError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServersListError'
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServersListError'
      parameters:
      - in: query
        name: q
        schema:
          type: string
        description: Search query for full-text and semantic search across server names and descriptions.
      - in: query
        name: page
        schema:
          type: integer
          minimum: 1
          maximum: 9007199254740991
        description: Page number (1-indexed).
      - in: query
        name: pageSize
        schema:
          type: integer
          minimum: 1
          maximum: 100
        description: Number of results per page (default 10, max 100).
      - in: query
        name: topK
        schema:
          type: integer
          minimum: 10
          maximum: 500
        description: Maximum number of candidate results to consider from the search index before pagination.
      - in: query
        name: fields
        schema:
          type: string
        description: Comma-separated list of fields to include in response
      - in: query
        name: ids
        schema:
          type: array
          items:
            type: string
            format: uuid
            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        description: Filter by specific server IDs.
      - in: query
        name: qualifiedName
        schema:
          type: string
        description: 'Exact match on the server''s qualified name (e.g. "smithery/hello-world"). Deprecated: use GET /servers/:namespace/:server instead.'
      - in: query
        name: namespace
        schema:
          type: string
        description: Filter by the namespace that owns the server.
      - in: query
        name: remote
        schema:
          type: string
          enum:
          - '0'
          - '1'
          - 'true'
          - 'false'
        description: Filter by remote status. Remote servers are accessed via URL; non-remote servers run locally via stdio.
      - in: query
        name: isDeployed
        schema:
          t

# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smithery-ai/refs/heads/main/openapi/smithery-ai-servers-api-openapi.yml