openapi: 3.1.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