Smithery servers API

openapi: 3.2.0
info:
  title: Smithery Platform connect Servers API
  description: API for the Smithery platform — discover, deploy, and manage MCP (Model Context Protocol) servers. Provides endpoints for browsing the server registry, managing deployments, creating scoped access tokens, and connecting to MCP servers.
  version: 1.0.0
servers:
- url: https://api.smithery.ai
security:
- bearerAuth: []
tags:
- name: servers
  description: Browse the MCP server registry, manage server configuration, and handle deployments
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.
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst server = await client.servers.get('qualifiedName');\n\nconsole.log(server.connections);"
    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.
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst server = await client.servers.create('qualifiedName');\n\nconsole.log(server.createdAt);"
    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.
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst server = await client.servers.update('qualifiedName');\n\nconsole.log(server.namespace);"
    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.
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst server = await client.servers.delete('qualifiedName');\n\nconsole.log(server.namespace);"
  /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.
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.servers.download('qualifiedName');\n\nconsole.log(response);\n\nconst content = await response.blob();\nconsole.log(content);"
  /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.
      x-codeSamples:
      - lang: JavaScript
        source: "import fs from 'fs';\nimport Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.servers.releases.deploy('qualifiedName', { payload: 'payload' });\n\nconsole.log(response.deploymentId);"
    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, AUTH_TIMEOUT, 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'
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const releaseListResponse of client.servers.releases.list('qualifiedName')) {\n  console.log(releaseListResponse.id);\n}"
  /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
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst release = await client.servers.releases.get('id', { qualifiedName: 'qualifiedName' });\n\nconsole.log(release.id);"
  /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
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.servers.releases.stream('id', { qualifiedName: 'qualifiedName' });\n\nconsole.log(response);"
  /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
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.servers.releases.resume('id', { qualifiedName: 'qualifiedName' });\n\nconsole.log(response.deploymentId);"
  /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.
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst logs = await client.servers.logs.list('qualifiedName');\n\nconsole.log(logs.invocations);"
  /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
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst secrets = await client.servers.secrets.list('qualifiedName');\n\nconsole.log(secrets);"
    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
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.servers.secrets.set('qualifiedName', { name: 'x', value: 'x' });\n\nconsole.log(response.success);"
  /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
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst secret = await client.servers.secrets.delete('secretName', {\n  qualifiedName: 'qualifiedName',\n});\n\nconsole.log(secret.success);"
  /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.
      x-codeSamples:
      - lang: JavaScript
        source: "import Smithery from '@smithery/api';\n\nconst client = new Smithery({\n  apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.servers.icon.upload('qualifiedName');\n\nconsole.log(response.iconUrl);"
    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:
            

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