openapi: 3.1.0 info: title: Smithery Platform 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 components: securitySchemes: bearerAuth: type: http scheme: bearer description: Smithery API key as Bearer token schemas: Health: type: object properties: status: type: string timestamp: type: string required: - status - timestamp additionalProperties: false HealthError: type: object properties: error: type: string example: Service unhealthy required: - error additionalProperties: false ConfigSchema: type: object propertyNames: type: string additionalProperties: x-stainless-any: true StdioConnection: type: object properties: type: type: string const: stdio bundleUrl: type: string format: uri runtime: type: string enum: - node - binary - python - bun configSchema: $ref: '#/components/schemas/ConfigSchema' required: - type - bundleUrl - runtime - configSchema additionalProperties: false id: StdioConnection HttpConnection: type: object properties: type: type: string const: http deploymentUrl: type: string configSchema: $ref: '#/components/schemas/ConfigSchema' required: - type - deploymentUrl - configSchema additionalProperties: false id: HttpConnection ServerSecurity: type: object properties: scanPassed: type: boolean example: true required: - scanPassed additionalProperties: false id: ServerSecurity ServerTool: type: object properties: name: type: string example: get_weather description: anyOf: - type: string - type: 'null' example: Get current weather inputSchema: $ref: '#/components/schemas/ToolInputSchema' outputSchema: $ref: '#/components/schemas/ToolOutputSchema' required: - name - description - inputSchema additionalProperties: false id: ServerTool ToolInputSchema: type: object properties: type: type: string const: object properties: $ref: '#/components/schemas/InputSchemaProperties' required: - type additionalProperties: false id: ToolInputSchema InputSchemaProperties: id: InputSchemaProperties type: object propertyNames: type: string additionalProperties: x-stainless-any: true ToolOutputSchema: id: ToolOutputSchema type: object properties: type: type: string const: object properties: $ref: '#/components/schemas/OutputSchemaProperties' required: type: array items: type: string required: - type additionalProperties: false OutputSchemaProperties: id: OutputSchemaProperties type: object propertyNames: type: string additionalProperties: {} ServerResource: type: object properties: name: type: string example: config://settings uri: type: string example: config://app/settings description: example: Application settings type: string mimeType: example: application/json type: string required: - name - uri additionalProperties: false id: ServerResource ServerPrompt: type: object properties: name: type: string example: summarize description: example: Summarize the given text type: string arguments: type: array items: type: object properties: name: type: string example: text description: example: The text to summarize type: string required: example: true type: boolean required: - name additionalProperties: false required: - name additionalProperties: false id: ServerPrompt Server: type: object properties: qualifiedName: type: string example: smithery/hello-world displayName: type: string example: Hello World description: type: string example: A simple hello world server iconUrl: anyOf: - type: string - type: 'null' example: https://example.com/icon.png remote: type: boolean example: true deploymentUrl: anyOf: - type: string - type: 'null' example: https://api.example.com connections: type: array items: anyOf: - $ref: '#/components/schemas/StdioConnection' - $ref: '#/components/schemas/HttpConnection' security: anyOf: - $ref: '#/components/schemas/ServerSecurity' - type: 'null' tools: anyOf: - type: array items: $ref: '#/components/schemas/ServerTool' - type: 'null' resources: anyOf: - type: array items: $ref: '#/components/schemas/ServerResource' - type: 'null' prompts: anyOf: - type: array items: $ref: '#/components/schemas/ServerPrompt' - type: 'null' required: - qualifiedName - displayName - description - iconUrl - remote - deploymentUrl - connections - security - tools - resources - prompts additionalProperties: false RegistryError: type: object properties: error: type: string example: Server not found required: - error additionalProperties: false ServersListQuery: type: object properties: q: description: >- Search query for full-text and semantic search across server names and descriptions. type: string page: description: Page number (1-indexed). type: integer minimum: 1 maximum: 9007199254740991 pageSize: description: Number of results per page (default 10, max 100). type: integer minimum: 1 maximum: 100 topK: description: >- Maximum number of candidate results to consider from the search index before pagination. The server applies a hard cap of 500 to keep the rerank window bounded; pass `seed` for stable deep pagination. type: integer minimum: 10 maximum: 500 fields: description: Comma-separated list of fields to include in response type: string ids: description: Filter by specific server IDs. 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)$ qualifiedName: description: >- Exact match on the server's qualified name (e.g. "smithery/hello-world"). Deprecated: use GET /servers/:namespace/:server instead. type: string namespace: description: Filter by the namespace that owns the server. type: string remote: description: >- Filter by remote status. Remote servers are accessed via URL; non-remote servers run locally via stdio. isDeployed: description: >- Filter by deployment status. Deployed servers are hosted on Smithery infrastructure. verified: description: Filter to only verified servers. smitheryManaged: description: Filter to servers whose namespace is owned by the Smithery org. ownerId: description: Filter by the server owner's user ID. type: string repoOwner: description: Filter by GitHub repository owner from repository_url. type: string repoName: description: Filter by GitHub repository name from repository_url. type: string seed: description: >- Random seed for deterministic pagination. When provided, results use a stable sort order that is consistent across pages for the same seed value. type: integer minimum: -9007199254740991 maximum: 9007199254740991 additionalProperties: false ServerSummary: type: object properties: id: type: string example: abc123 qualifiedName: type: string description: Unique identifier in namespace/slug format. example: smithery/hello-world namespace: anyOf: - type: string - type: 'null' description: The namespace this server belongs to, or null if unassigned. example: smithery-ai slug: anyOf: - type: string - type: 'null' description: URL-friendly short name within the namespace. example: hello-world displayName: type: string example: Hello World description: type: string example: A simple hello world server iconUrl: anyOf: - type: string - type: 'null' example: https://example.com/icon.png verified: type: boolean description: Whether this server has been verified by Smithery. example: true useCount: type: number description: Total number of times this server has been connected to. example: 42 remote: anyOf: - type: boolean - type: 'null' description: >- Whether the server is accessed via URL (true) or runs locally via stdio (false). Null if unknown. example: true isDeployed: type: boolean description: Whether the server is currently hosted on Smithery infrastructure. example: true createdAt: type: string description: ISO 8601 timestamp of when the server was registered. example: '2024-01-01T00:00:00.000Z' homepage: type: string description: >- The server owner's homepage URL, or the server's Smithery page as a fallback. Will become nullable in a future release. example: https://example.com bySmithery: type: boolean description: >- Whether this server is maintained by Smithery (i.e. owned by the Smithery organization). example: false owner: anyOf: - type: string - type: 'null' description: User ID of the server owner, or null for community servers. example: user_abc123 score: anyOf: - type: number - type: 'null' description: RRF relevance score from search (null for browse requests). example: 0.016 required: - id - qualifiedName - namespace - slug - displayName - description - iconUrl - verified - useCount - remote - isDeployed - createdAt - homepage - bySmithery - owner - score additionalProperties: false id: ServerSummary ServersListResponse: type: object properties: servers: type: array items: $ref: '#/components/schemas/ServerSummary' pagination: type: object properties: currentPage: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Current page number (1-indexed). example: 1 pageSize: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Number of results per page. example: 10 totalPages: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Total number of pages available. example: 5 totalCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Total number of matching servers. example: 42 required: - currentPage - pageSize - totalPages - totalCount additionalProperties: false required: - servers - pagination additionalProperties: false ServersListError: type: object properties: error: type: string example: Server not found required: - error additionalProperties: false SkillsListQuery: type: object properties: q: description: >- Search query for full-text and semantic search across skill names and descriptions. type: string category: description: Filter by skill category (e.g. 'code', 'data', 'web'). type: string namespace: description: Filter by the namespace that owns the skill. type: string slug: description: >- Filter by exact skill slug within a namespace. Deprecated: use GET /skills/:namespace/:slug instead. type: string ownerId: description: Filter by the skill owner's organization ID. type: string verified: description: Filter by whether the skill's namespace is verified. type: boolean page: description: Page number (1-indexed). type: integer minimum: 1 maximum: 9007199254740991 pageSize: description: Number of results per page (default 20, max 100). type: integer minimum: 1 maximum: 100 topK: description: >- Maximum number of candidate results to consider from the search index before pagination. The server applies a hard cap of 500 to keep the rerank window bounded; pass `seed` for stable deep pagination. type: integer minimum: 10 maximum: 500 fields: description: Comma-separated list of fields to include in response type: string seed: description: >- Random seed for deterministic pagination. When provided, results use a stable sort order that is consistent across pages for the same seed value. type: integer minimum: -9007199254740991 maximum: 9007199254740991 additionalProperties: false SkillSummary: type: object properties: id: type: string namespace: type: string description: Namespace that owns this skill. slug: type: string description: URL-friendly short name within the namespace. displayName: type: string description: type: string prompt: anyOf: - type: string - type: 'null' description: The prompt template for this skill, or null if not publicly visible. qualityScore: type: number description: Computed quality score from 0 to 1. externalStars: description: GitHub star count of the source repository, if applicable. type: number externalForks: description: GitHub fork count of the source repository, if applicable. type: number totalActivations: description: Total number of times this skill has been activated. type: number uniqueUsers: description: Number of distinct users who have activated this skill. type: number categories: description: List of categories this skill belongs to. type: array items: type: string servers: description: Qualified names of MCP servers this skill depends on. type: array items: type: string gitUrl: description: URL to the skill's source repository. anyOf: - type: string - type: 'null' verified: type: boolean description: Whether this skill's namespace is verified. listed: type: boolean description: Whether this skill is publicly listed in the registry. createdAt: type: string description: ISO 8601 timestamp of when the skill was created. required: - id - namespace - slug - displayName - description - prompt - qualityScore - verified - listed - createdAt additionalProperties: false id: SkillSummary SkillsListResponse: type: object properties: skills: type: array items: $ref: '#/components/schemas/SkillSummary' pagination: type: object properties: currentPage: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Current page number (1-indexed). pageSize: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Number of results per page. totalPages: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Total number of pages available. totalCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Total number of matching skills. required: - currentPage - pageSize - totalPages - totalCount additionalProperties: false required: - skills - pagination additionalProperties: false SkillsListError: type: object properties: error: type: string required: - error additionalProperties: false DeployResponse: type: object properties: deploymentId: 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: Unique identifier for this release. example: 123e4567-e89b-12d3-a456-426614174000 status: type: string description: Initial status. Will be WORKING while the release is in progress. example: WORKING mcpUrl: type: string format: uri description: The MCP endpoint URL for connecting to this server once published. example: https://slug.run.tools warnings: description: Non-fatal warnings encountered during submission. type: array items: type: string required: - deploymentId - status - mcpUrl additionalProperties: false DeploymentLogEntryError: type: object properties: message: type: string additionalProperties: false id: DeploymentLogEntryError DeploymentLogEntry: type: object properties: stage: type: string enum: - deploy - scan - metadata - publish description: >- Pipeline stage: deploy (bundle upload), scan (security/OAuth check), metadata (tool discovery), publish (generated artifacts). level: type: string description: 'Log level: ''start'', ''end'', ''info'', ''success'', or ''failure''.' message: type: string description: Human-readable log message. timestamp: type: string description: ISO 8601 timestamp of the log entry. error: description: Error details, present only when the stage failed. $ref: '#/components/schemas/DeploymentLogEntryError' required: - stage - level - message - timestamp additionalProperties: false DeploymentInfo: 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' logs: description: Pipeline log entries. Only included when fetching a single release. type: array items: $ref: '#/components/schemas/DeploymentLogEntry' 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 additionalProperties: false DeploymentList: 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 additionalProperties: false DeploymentError: type: object properties: error: type: string example: Server not found required: - error additionalProperties: false ResumeResponse: type: object properties: status: type: string example: WORKING deploymentId: 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)$ required: - status - deploymentId additionalProperties: false LogsQuery: type: object properties: from: example: '2026-01-01T00:00:00Z' description: Start of time range (ISO 8601). type: string to: example: '2026-01-01T01:00:00Z' description: End of time range (ISO 8601). type: string limit: example: 20 description: Max invocations to return. Defaults to 20. type: integer minimum: 1 maximum: 100 search: example: error description: Text search across log messages. type: string additionalProperties: false RuntimeLogEntry: type: object properties: timestamp: type: string example: '2026-01-04 10:53:39' level: type: string example: info message: type: string example: Processing request... required: - timestamp - level - message additionalProperties: false ExceptionEntry: type: object properties: timestamp: type: string example: '2026-01-04 10:53:39' name: type: string example: TypeError message: type: string example: Cannot read property 'x' of undefined required: - timestamp - name - message additionalProperties: false InvocationRequest: type: object properties: method: type: string example: POST url: type: string example: https://gateway.smithery.ai/@smithery/unicorn required: - method - url additionalProperties: false id: InvocationRequest InvocationResponse: type: object properties: status: type: number example: 200 outcome: type: string example: ok required: - status - outcome additionalProperties: false id: InvocationResponse InvocationDuration: type: object properties: cpuMs: type: number example: 5 wallMs: type: number example: 743 required: - cpuMs - wallMs additionalProperties: false id: InvocationDuration Invocation: type: object properties: id: type: string example: 625f9ce6-f179-4f23-b3e3-4de28b52b39d timestamp: type: string example: '2026-01-04 10:53:39' request: $ref: '#/components/schemas/InvocationRequest' response: $ref: '#/components/schemas/InvocationResponse' duration: $ref: '#/components/schemas/InvocationDuration' logs: type: array items: $ref: '#/components/schemas/RuntimeLogEntry' exceptions: type: array items: $ref: '#/components/schemas/ExceptionEntry' required: - id - timestamp - request - response - duration - logs - exceptions additionalProperties: false RuntimeLogsResponse: type: object properties: invocations: type: array items: $ref: '#/components/schemas/Invocation' total: type: number description: Total invocations matching query required: - invocations - total additionalProperties: false RuntimeLogsError: type: object properties: error: type: string example: Server not found required: - error additionalProperties: false Namespace: type: object properties: name: type: string example: myorg createdAt: type: string example: '2024-01-01T00:00:00.000Z' required: - name - createdAt additionalProperties: false NamespaceSearchResult: type: object properties: name: type: string example: anthropic required: - name additionalProperties: false NamespacesResponse: type: object properties: namespaces: type: array items: $ref: '#/components/schemas/Namespace' required: - namespaces additionalProperties: false NamespacesSearchResponse: type: object properties: namespaces: type: array items: $ref: '#/components/schemas/NamespaceSearchResult' 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 additionalProperties: false required: - namespaces - pagination additionalProperties: false NamespacesError: type: object properties: error: type: string example: Unauthorized required: - error additionalProperties: false CreateNamespaceResponse: type: object properties: name: type: string example: myorg createdAt: type: string example: '2024-01-01T00:00:00.000Z' required: - name - createdAt additionalProperties: false CreateServerRequest: type: object properties: displayName: example: My Server type: string description: example: A simple server type: string additionalProperties: false CreateServerResponse: type: object properties: namespace: type: string example: myorg server: type: string example: my-server 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 additionalProperties: false CreateServerError: type: object properties: error: type: string example: 'Forbidden: You don''t own this server' required: - error additionalProperties: false HostedDeployPayload: type: object properties: type: type: string const: hosted stateful: default: false type: boolean hasAuthAdapter: default: false type: boolean configSchema: type: object propertyNames: type: string additionalProperties: {} serverCard: $ref: '#/components/schemas/ServerCard' secretNames: type: array items: type: string source: type: object properties: commit: type: string branch: type: string additionalProperties: false required: - type - stateful - hasAuthAdapter additionalProperties: false ServerCard: type: object properties: serverInfo: type: object properties: name: type: string title: type: string icons: type: array items: type: object properties: src: type: string mimeType: type: string sizes: type: array items: type: string theme: type: string enum: - light - dark required: - src additionalProperties: false version: type: string websiteUrl: type: string description: type: string required: - name - version additionalProperties: false tools: type: array items: type: object properties: name: type: string title: type: string icons: type: array items: type: object properties: src: type: string mimeType: type: string sizes: type: array items: type: string theme: type: string enum: - light - dark required: - src additionalProperties: false description: type: string inputSchema: type: object properties: type: type: string const: object properties: type: object propertyNames: type: string additionalProperties: {} required: type: array items: type: string required: - type additionalProperties: {} outputSchema: type: object properties: type: type: string const: object properties: type: object propertyNames: type: string additionalProperties: {} required: type: array items: type: string required: - type additionalProperties: {} annotations: type: object properties: title: type: string readOnlyHint: type: boolean destructiveHint: type: boolean idempotentHint: type: boolean openWorldHint: type: boolean additionalProperties: false execution: type: object properties: taskSupport: type: string enum: - required - optional - forbidden additionalProperties: false _meta: type: object propertyNames: type: string additionalProperties: {} required: - name - inputSchema additionalProperties: false resources: type: array items: type: object properties: name: type: string title: type: string icons: type: array items: type: object properties: src: type: string mimeType: type: string sizes: type: array items: type: string theme: type: string enum: - light - dark required: - src additionalProperties: false uri: type: string description: type: string mimeType: type: string annotations: type: object properties: audience: type: array items: type: string enum: - user - assistant priority: type: number minimum: 0 maximum: 1 lastModified: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ additionalProperties: false _meta: type: object properties: {} additionalProperties: {} required: - name - uri additionalProperties: false prompts: type: array items: type: object properties: name: type: string title: type: string icons: type: array items: type: object properties: src: type: string mimeType: type: string sizes: type: array items: type: string theme: type: string enum: - light - dark required: - src additionalProperties: false description: type: string arguments: type: array items: type: object properties: name: type: string description: type: string required: type: boolean required: - name additionalProperties: false _meta: type: object properties: {} additionalProperties: {} required: - name additionalProperties: false required: - serverInfo additionalProperties: {} ExternalDeployPayload: type: object properties: type: type: string const: external upstreamUrl: type: string format: uri configSchema: type: object propertyNames: type: string additionalProperties: {} scanCredentials: type: object propertyNames: type: string additionalProperties: type: string required: - type - upstreamUrl additionalProperties: false StdioDeployPayload: type: object properties: type: type: string const: stdio runtime: type: string enum: - node - binary - python - bun configSchema: type: object propertyNames: type: string additionalProperties: {} serverCard: $ref: '#/components/schemas/ServerCard' required: - type - runtime additionalProperties: false id: StdioDeployPayload DeployPayload: oneOf: - $ref: '#/components/schemas/HostedDeployPayload' - $ref: '#/components/schemas/ExternalDeployPayload' - $ref: '#/components/schemas/StdioDeployPayload' DeploymentTarget: type: string enum: - local - remote BuildConfig: description: Custom build configuration for cloud builds type: object properties: installCommand: description: Custom install command. Defaults to 'npm install' type: string buildCommand: description: Custom build command. Defaults to 'npm run build' type: string outputDirectory: description: >- Directory containing the build output, relative to base directory. Defaults to '.smithery' type: string additionalProperties: false ProjectConfig: type: object properties: target: type: string enum: - local - remote build: description: Custom build configuration for cloud builds type: object properties: installCommand: description: Custom install command. Defaults to 'npm install' type: string buildCommand: description: Custom build command. Defaults to 'npm run build' type: string outputDirectory: description: >- Directory containing the build output, relative to base directory. Defaults to '.smithery' type: string additionalProperties: false additionalProperties: {} Constraint: type: object properties: namespaces: description: >- Namespace(s) the token is scoped to. Accepts a single slug or an array. example: - my-app anyOf: - type: string - type: array items: type: string resources: description: >- Resource type(s) the token may access: connections, servers, namespaces, or skills. example: - connections anyOf: - type: string enum: - connections - servers - namespaces - skills - type: array items: type: string enum: - connections - servers - namespaces - skills operations: description: 'Operation(s) the token may perform: read, write, or execute.' example: - read anyOf: - type: string enum: - read - write - execute - type: array items: type: string enum: - read - write - execute metadata: description: >- Key-value metadata for fine-grained filtering. A single object requires all pairs to match (AND). An array of objects requires any one to match (OR-of-AND), e.g. [{"userId":"alice"},{"team":"backend"}] grants access when either condition is met. example: - userId: alice anyOf: - type: object propertyNames: type: string additionalProperties: type: string - type: array items: type: object propertyNames: type: string additionalProperties: type: string ttl: description: >- Time-to-live for the constraint. Accepts seconds (number) or a duration string such as "1h", "30m", or "20s". example: 1h anyOf: - type: string - type: number rpcReqMatch: description: >- MCP JSON-RPC request matching rules. Keys are dot-paths into the request body (e.g. "params.name", "method"). Values are regex patterns. All entries must match (AND). example: params.name: ^(create_issue|search_issues)$ type: object propertyNames: type: string maxLength: 200 additionalProperties: type: string maxLength: 500 additionalProperties: false description: >- A policy constraint that restricts a token's scope. All specified fields within a single constraint are AND'd together. When multiple constraints are passed in the policy array, each is applied as an independent attenuation block. CreateTokenRequest: type: object properties: policy: description: >- Constraint objects to restrict the token. Each constraint may include a `ttl` field (max 24 hours). Default TTL is 1 hour. Maximum is 24 hours. minItems: 1 type: array items: $ref: '#/components/schemas/Constraint' organizationId: description: >- Optional organization ID to scope the token to. When provided, the token is minted with org context. The authenticated user must be an admin or owner of the organization. example: org_01H1234567890 type: string additionalProperties: false CreateTokenResponse: type: object properties: token: type: string description: The signed service token. expiresAt: type: string description: ISO 8601 timestamp when the token expires. example: '2024-01-01T01:00:00.000Z' required: - token - expiresAt additionalProperties: false TokenError: type: object properties: error: type: string example: unauthorized message: example: Invalid API key type: string required: - error additionalProperties: false DomainResource: type: object properties: id: type: string const: managed example: managed type: type: string const: managed example: managed hostname: type: string example: my-server.run.tools subdomain: type: string example: my-server createdAt: type: string example: '2024-01-01T00:00:00.000Z' updatedAt: type: string example: '2024-01-01T00:00:00.000Z' required: - id - type - hostname - subdomain - createdAt - updatedAt additionalProperties: false DomainListResponse: type: object properties: domains: type: array items: $ref: '#/components/schemas/DomainResource' required: - domains additionalProperties: false UpdateDomainRequest: type: object properties: subdomain: type: string pattern: ^[a-z][a-z0-9-]{0,61}[a-z0-9]$ required: - subdomain additionalProperties: false DomainsError: type: object properties: error: type: string example: Server not found required: - error additionalProperties: false CreateTeamApiKeyBody: type: object properties: name: type: string minLength: 1 maxLength: 256 description: Name for the team API key required: - name additionalProperties: false TeamApiKey: type: object properties: id: type: string name: type: string createdAt: type: string required: - id - name - createdAt additionalProperties: false TeamApiKeyCreated: type: object properties: id: type: string name: type: string key: type: string createdAt: type: string required: - id - name - key - createdAt additionalProperties: false Error: type: object properties: error: type: string example: not_found message: type: string example: Resource not found required: - error - message additionalProperties: false ValidationError: type: object properties: error: type: string const: validation_error message: type: string example: Invalid request required: - error - message additionalProperties: false Success: type: object properties: success: type: boolean const: true required: - success additionalProperties: false MockConfig: type: object properties: enabled: type: boolean description: Turn mock mode on for this connection. scenario: description: >- Natural-language starting-state for the simulator (threaded into the LLM system prompt so generated data is consistent with the scenario across calls). example: >- Slack workspace with an active #community-ops channel containing recent event-planning messages, plus 50 Airtable candidate records with mixed tenure and interests. type: string required: - enabled additionalProperties: false id: MockConfig CreateConnectionRequest: type: object properties: transport: description: >- Connection transport. Use `uplink` for a local server paired over Smithery CLI. example: http type: string enum: - http - uplink mcpUrl: description: >- URL of the MCP server. Required for HTTP connections. Omit for uplink connections. example: https://mcp.example.com/sse type: string format: uri name: description: Human-readable name (optional, defaults to connection ID) example: My MCP Server type: string minLength: 1 maxLength: 255 metadata: description: Custom metadata for filtering connections example: userId: user123 team: engineering type: object propertyNames: type: string additionalProperties: {} headers: description: >- Custom headers to send with MCP requests (stored securely, not returned in responses) example: X-API-Key: secret-key type: object propertyNames: type: string additionalProperties: type: string mock: description: >- Run this connection in mock mode. Tool calls are LLM-simulated against the registry's scanned schemas and never reach the upstream server. Provide an optional `scenario` to seed the simulator with a starting-state description. Registry servers only; frozen at creation (cannot be toggled via PUT). example: enabled: true scenario: A developer inbox with 3 unread Q4 planning threads. $ref: '#/components/schemas/MockConfig' additionalProperties: false UpsertConnectionRequest: type: object properties: transport: description: >- Connection transport. Defaults to the existing connection transport when updating. example: http type: string enum: - http - uplink mcpUrl: description: >- URL of the MCP server. Required when creating a new connection. Optional when updating — omit to keep the existing URL. example: https://mcp.example.com/sse type: string format: uri name: description: Human-readable name (optional, defaults to connection ID) example: My MCP Server type: string minLength: 1 maxLength: 255 metadata: description: Custom metadata for filtering connections example: userId: user123 team: engineering type: object propertyNames: type: string additionalProperties: {} headers: description: >- Custom headers to send with MCP requests (stored securely, not returned in responses) example: X-API-Key: secret-key type: object propertyNames: type: string additionalProperties: type: string mock: description: >- Run this connection in mock mode. Only honored on first creation; ignored on updates to an existing connection. example: enabled: true $ref: '#/components/schemas/MockConfig' additionalProperties: false CredentialProfileHttp: type: object properties: headers: type: object propertyNames: type: string additionalProperties: $ref: '#/components/schemas/HttpInputField' query: type: object propertyNames: type: string additionalProperties: $ref: '#/components/schemas/HttpInputField' additionalProperties: false id: CredentialProfileHttp HttpInputField: type: object properties: label: type: string description: type: string required: type: boolean required: - label additionalProperties: false id: HttpInputField ConnectionStatus: oneOf: - type: object properties: state: type: string const: connected required: - state additionalProperties: false title: ConnectionStatusConnected - type: object properties: state: type: string const: disconnected required: - state additionalProperties: false title: ConnectionStatusDisconnected - type: object properties: state: type: string const: auth_required setupUrl: description: Hosted Smithery URL for completing setup and OAuth type: string format: uri authorizationUrl: description: Deprecated compatibility alias for setupUrl deprecated: true type: string format: uri required: - state additionalProperties: false title: ConnectionStatusAuthRequired - type: object properties: state: type: string const: input_required setupUrl: description: Hosted Smithery URL for completing setup in the browser type: string format: uri http: $ref: '#/components/schemas/CredentialProfileHttp' missing: type: object properties: headers: type: array items: type: string query: type: array items: type: string required: - headers - query additionalProperties: false required: - state - http - missing additionalProperties: false title: ConnectionStatusInputRequired - type: object properties: state: type: string const: error message: type: string description: Error message required: - state - message additionalProperties: false title: ConnectionStatusError ServerInfo: type: object properties: name: type: string title: type: string icons: type: array items: type: object properties: src: type: string mimeType: type: string sizes: type: array items: type: string theme: type: string enum: - light - dark required: - src additionalProperties: false version: type: string websiteUrl: type: string description: type: string required: - name - version additionalProperties: false Connection: type: object properties: connectionId: type: string description: Connection ID (auto-generated or developer-defined) example: clever-dolphin-a9X3 name: type: string description: Human-readable name transport: description: Connection transport type: string enum: - http - uplink mcpUrl: anyOf: - type: string - type: 'null' description: MCP server URL. Null for uplink connections. metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' mock: description: >- Mock-mode config: `{enabled: true, scenario?}` when LLM-simulated, absent otherwise. $ref: '#/components/schemas/MockConfig' iconUrl: anyOf: - type: string - type: 'null' createdAt: description: ISO 8601 timestamp type: string status: description: Last known connection status $ref: '#/components/schemas/ConnectionStatus' serverInfo: description: Server information from MCP initialization (name, version) $ref: '#/components/schemas/ServerInfo' required: - connectionId - name - mcpUrl - metadata additionalProperties: false ConnectionsListQuery: type: object properties: limit: description: Maximum number of items to return (default 100, max 100) example: 50 type: integer minimum: 1 maximum: 100 cursor: description: Pagination cursor from previous response's nextCursor type: string name: description: Filter by exact connection name type: string mcpUrl: description: Filter by exact MCP server URL type: string additionalProperties: false ConnectionsListResponse: type: object properties: connections: type: array items: $ref: '#/components/schemas/Connection' nextCursor: anyOf: - type: string - type: 'null' description: Cursor for next page, null if no more results required: - connections - nextCursor additionalProperties: false LooseObject: type: object propertyNames: type: string additionalProperties: x-stainless-any: true Tool: type: object properties: name: type: string title: type: string icons: type: array items: type: object properties: src: type: string mimeType: type: string sizes: type: array items: type: string theme: type: string enum: - light - dark required: - src additionalProperties: false description: type: string inputSchema: type: object properties: type: type: string const: object properties: type: object propertyNames: type: string additionalProperties: {} required: type: array items: type: string required: - type additionalProperties: {} outputSchema: type: object properties: type: type: string const: object properties: type: object propertyNames: type: string additionalProperties: {} required: type: array items: type: string required: - type additionalProperties: {} annotations: type: object properties: title: type: string readOnlyHint: type: boolean destructiveHint: type: boolean idempotentHint: type: boolean openWorldHint: type: boolean additionalProperties: false execution: type: object properties: taskSupport: type: string enum: - required - optional - forbidden additionalProperties: false _meta: type: object propertyNames: type: string additionalProperties: {} required: - name - inputSchema additionalProperties: false ToolList: type: object properties: tools: type: array items: $ref: '#/components/schemas/Tool' required: - tools additionalProperties: false ToolResponse: anyOf: - $ref: '#/components/schemas/Tool' - $ref: '#/components/schemas/ToolList' TriggerDefinition: type: object properties: name: type: string description: Trigger name exposed by the MCP server example: page.updated description: type: string delivery: type: array items: type: string description: Supported delivery modes example: - webhook inputSchema: description: JSON Schema for the params required to create the trigger $ref: '#/components/schemas/LooseObject' payloadSchema: description: JSON Schema for the event payload delivered by the trigger $ref: '#/components/schemas/LooseObject' required: - name - delivery additionalProperties: false TriggerDefinitionList: type: array items: $ref: '#/components/schemas/TriggerDefinition' TriggerDelivery: type: object properties: url: type: string description: >- HTTPS webhook destination where the upstream MCP server delivers events. example: https://my-app.example.com/events secret: type: string description: >- Standard Webhooks signing secret (whsec_). The upstream MCP server signs each delivery with this. example: whsec_dGVzdF9zZWNyZXRfMjRfYnl0ZXNfbWluaW11bSE= required: - url - secret additionalProperties: false UnsubscribeDelivery: type: object properties: url: type: string description: >- The delivery URL of the subscription to remove. Together with name+params it forms the subscription key. example: https://my-app.example.com/events required: - url additionalProperties: false CreateTriggerRequest: type: object properties: params: default: {} description: Trigger-specific parameters defined by the trigger inputSchema $ref: '#/components/schemas/LooseObject' delivery: $ref: '#/components/schemas/TriggerDelivery' required: - params - delivery additionalProperties: false DeleteTriggerRequest: type: object properties: params: default: {} description: >- The same params used at subscribe time. Forms part of the subscription key. $ref: '#/components/schemas/LooseObject' delivery: $ref: '#/components/schemas/UnsubscribeDelivery' required: - params - delivery additionalProperties: false TriggerSubscription: type: object properties: id: type: string description: >- Stable subscription id derived from (namespace, connection, name, params, delivery.url). Used by the receiver to route via X-MCP-Subscription-Id. example: trg_01HW1234567890 refreshBefore: type: string description: >- ISO 8601 timestamp at which the subscription expires unless refreshed. example: '2026-04-22T13:00:00.000Z' required: - id - refreshBefore additionalProperties: false JsonRpcRequest: type: object properties: jsonrpc: default: '2.0' type: string const: '2.0' id: anyOf: - type: string - type: number method: type: string description: MCP method to call example: tools/list params: description: Method parameters required: - jsonrpc - method additionalProperties: false JsonRpcResponse: type: object properties: jsonrpc: type: string const: '2.0' id: anyOf: - type: string - type: number - type: 'null' result: {} required: - jsonrpc - id additionalProperties: false JsonRpcError: type: object properties: jsonrpc: type: string const: '2.0' id: anyOf: - type: string - type: number - type: 'null' error: type: object properties: code: type: number example: -32600 message: type: string example: Invalid Request data: {} required: - code - message additionalProperties: false required: - jsonrpc - id - error additionalProperties: false AuthRequiredError: type: object properties: jsonrpc: type: string const: '2.0' id: anyOf: - type: string - type: number - type: 'null' error: type: object properties: code: type: number const: -32001 message: type: string const: Authorization required data: type: object properties: authorizationUrl: type: string format: uri required: - authorizationUrl additionalProperties: false required: - code - message - data additionalProperties: false required: - jsonrpc - id - error additionalProperties: false InputRequiredError: type: object properties: jsonrpc: type: string const: '2.0' id: anyOf: - type: string - type: number - type: 'null' error: type: object properties: code: type: number const: -32002 message: type: string const: Input required data: type: object properties: http: $ref: '#/components/schemas/CredentialProfileHttp' missing: type: object properties: headers: type: array items: type: string query: type: array items: type: string required: - headers - query additionalProperties: false required: - http - missing additionalProperties: false required: - code - message - data additionalProperties: false required: - jsonrpc - id - error additionalProperties: false security: - bearerAuth: [] tags: - name: servers description: >- Browse the MCP server registry, manage server configuration, and handle deployments - name: skills description: Discover and search reusable prompt-based skills for MCP servers - name: tools description: Search for MCP tools across all registered servers paths: /health: get: operationId: getHealth summary: Health check description: Check if the service is running responses: '200': description: Service is healthy content: application/json: schema: $ref: '#/components/schemas/Health' '500': description: Service unhealthy content: application/json: schema: $ref: '#/components/schemas/HealthError' x-codeSamples: - lang: JavaScript source: |- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const response = await client.health.check(); console.log(response.status); /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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const server = await client.servers.get('qualifiedName'); console.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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const server = await client.servers.create('qualifiedName'); console.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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const server = await client.servers.update('qualifiedName'); console.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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const server = await client.servers.delete('qualifiedName'); console.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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const response = await client.servers.download('qualifiedName'); console.log(response); const content = await response.blob(); console.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'; import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const response = await client.servers.releases.deploy('qualifiedName', { payload: 'payload' }); console.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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const releaseListResponse of client.servers.releases.list('qualifiedName')) { console.log(releaseListResponse.id); } /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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const release = await client.servers.releases.get('id', { qualifiedName: 'qualifiedName' }); console.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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const response = await client.servers.releases.stream('id', { qualifiedName: 'qualifiedName' }); console.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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const response = await client.servers.releases.resume('id', { qualifiedName: 'qualifiedName' }); console.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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const logs = await client.servers.logs.list('qualifiedName'); console.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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const secrets = await client.servers.secrets.list('qualifiedName'); console.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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const response = await client.servers.secrets.set('qualifiedName', { name: 'x', value: 'x' }); console.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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const secret = await client.servers.secrets.delete('secretName', { qualifiedName: 'qualifiedName', }); console.log(secret.success); /servers/{qualifiedName}/domains: get: operationId: getServers:namespaceDomains tags: - domains summary: List domains description: List the domains for a server. responses: '200': description: Domain list content: application/json: schema: $ref: '#/components/schemas/DomainListResponse' '404': description: Server not found content: application/json: schema: $ref: '#/components/schemas/DomainsError' 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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const domains = await client.servers.domains.list('qualifiedName'); console.log(domains.domains); /servers/{qualifiedName}/domains/{domainId}: patch: operationId: patchServers:namespaceDomains:domainId requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateDomainRequest' tags: - domains summary: Update managed domain description: Update the managed run.tools slug for a server. responses: '200': description: Managed domain updated content: application/json: schema: $ref: '#/components/schemas/DomainResource' '404': description: Domain not found content: application/json: schema: $ref: '#/components/schemas/DomainsError' '409': description: Conflict — managed run.tools slug already taken content: application/json: schema: $ref: '#/components/schemas/DomainsError' 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: domainId required: true x-hidden: true x-codeSamples: - lang: JavaScript source: |- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const domain = await client.servers.domains.update('domainId', { qualifiedName: 'qualifiedName', subdomain: 'subdomain', }); console.log(domain.id); /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'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const response = await client.servers.icon.upload('qualifiedName'); console.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: 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. x-codeSamples: - lang: JavaScript source: |- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const icon = await client.servers.icon.delete('qualifiedName'); console.log(icon.success); 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. x-codeSamples: - lang: JavaScript source: |- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const icon = await client.servers.icon.get('qualifiedName'); console.log(icon); const content = await icon.blob(); console.log(content); /servers/{qualifiedName}/experimental/tools/{toolName}/output-schema: get: operationId: getServers:namespaceExperimentalTools:toolNameOutput-schema tags: - servers summary: Infer a tool output schema description: >- Infer a best-effort Zod schema from recent successful Tinybird tool outputs. All discovered object fields are marked optional. responses: '200': description: Inferred tool output schema content: application/json: schema: type: object properties: qualifiedName: type: string example: smithery-ai/github toolName: type: string example: search_repositories sampleCount: type: number example: 25 zodSchema: type: string example: 'z.object({ "items": z.array(z.object({})).optional() })' required: - qualifiedName - toolName - sampleCount - zodSchema id: ToolOutputSchemaResponse '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string example: No output samples found required: - error id: ToolOutputSchemaError '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string example: No output samples found required: - error id: ToolOutputSchemaError '404': description: No output samples found content: application/json: schema: type: object properties: error: type: string example: No output samples found required: - error id: ToolOutputSchemaError '503': description: Tinybird is not configured content: application/json: schema: type: object properties: error: type: string example: No output samples found required: - error id: ToolOutputSchemaError 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: toolName required: true /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. The server applies a hard cap of 500 to keep the rerank window bounded; pass `seed` for stable deep 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: type: string enum: - '0' - '1' - 'true' - 'false' description: >- Filter by deployment status. Deployed servers are hosted on Smithery infrastructure. - in: query name: verified schema: type: string enum: - '0' - '1' - 'true' - 'false' description: Filter to only verified servers. - in: query name: smitheryManaged schema: type: string enum: - '0' - '1' - 'true' - 'false' description: Filter to servers whose namespace is owned by the Smithery org. - in: query name: ownerId schema: type: string description: Filter by the server owner's user ID. - in: query name: repoOwner schema: type: string description: Filter by GitHub repository owner from repository_url. - in: query name: repoName schema: type: string description: Filter by GitHub repository name from repository_url. - in: query name: seed schema: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Random seed for deterministic pagination. When provided, results use a stable sort order that is consistent across pages for the same seed value. x-codeSamples: - lang: JavaScript source: |- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const serverListResponse of client.servers.list()) { console.log(serverListResponse.id); } /skills: get: operationId: getSkills tags: - skills summary: List or search skills description: >- Search and browse reusable prompt-based skills. Supports full-text and semantic search via the `q` parameter, and filtering by category, namespace, or slug. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SkillsListResponse' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/SkillsListError' parameters: - in: query name: q schema: type: string description: >- Search query for full-text and semantic search across skill names and descriptions. - in: query name: category schema: type: string description: Filter by skill category (e.g. 'code', 'data', 'web'). - in: query name: namespace schema: type: string description: Filter by the namespace that owns the skill. - in: query name: slug schema: type: string description: >- Filter by exact skill slug within a namespace. Deprecated: use GET /skills/:namespace/:slug instead. - in: query name: ownerId schema: type: string description: Filter by the skill owner's organization ID. - in: query name: verified schema: type: boolean description: Filter by whether the skill's namespace is verified. - 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 20, 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. The server applies a hard cap of 500 to keep the rerank window bounded; pass `seed` for stable deep pagination. - in: query name: fields schema: type: string description: Comma-separated list of fields to include in response - in: query name: seed schema: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Random seed for deterministic pagination. When provided, results use a stable sort order that is consistent across pages for the same seed value. x-codeSamples: - lang: JavaScript source: |- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const skillListResponse of client.skills.list()) { console.log(skillListResponse.id); } post: operationId: postSkills tags: - skills summary: Create a new skill (deprecated) description: >- **Deprecated:** Use PUT /skills/{namespace}/{slug} instead. Create a new skill by linking a GitHub repository containing a SKILL.md file. deprecated: true responses: '200': description: Skill created successfully content: application/json: schema: type: object properties: id: type: string namespace: type: string slug: type: string displayName: type: string description: type: string gitUrl: type: string listed: type: boolean createdAt: type: string required: - id - namespace - slug - displayName - description - gitUrl - listed - createdAt id: CreateSkillResponse '400': description: Invalid request content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError '403': description: Forbidden - user does not own the namespace content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError '404': description: Namespace not found or SKILL.md not found content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError '409': description: Skill with this slug or git URL already exists content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError requestBody: content: application/json: schema: type: object properties: namespace: type: string minLength: 1 description: The namespace to create the skill in. slug: type: string minLength: 1 pattern: ^[a-z0-9-]+$ description: URL-friendly identifier for the skill. gitUrl: type: string format: uri description: GitHub URL pointing to a repository with SKILL.md required: - namespace - slug - gitUrl id: CreateSkillRequest x-codeSamples: - lang: JavaScript source: |- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const skill = await client.skills.create({ gitUrl: 'https://example.com', namespace: 'x', slug: 'slug', }); console.log(skill.id); /skills/{namespace}/{slug}: get: operationId: getSkills:namespace:slug tags: - skills summary: Get a skill description: Get a single skill by its namespace and slug. responses: '200': description: Skill found content: application/json: schema: type: object properties: id: type: string namespace: type: string slug: type: string displayName: type: string description: type: string prompt: type: string qualityScore: type: number externalStars: type: number externalForks: type: number totalActivations: type: number uniqueUsers: type: number categories: type: array items: type: string servers: type: array items: type: string gitUrl: anyOf: - type: string - type: 'null' verified: type: boolean description: Whether this skill's namespace is verified. listed: type: boolean owner: anyOf: - type: string - type: 'null' description: Organization ID of the skill owner (from namespace) createdAt: type: string required: - id - namespace - slug - displayName - description - prompt - qualityScore - externalStars - externalForks - totalActivations - uniqueUsers - categories - servers - gitUrl - verified - listed - owner - createdAt id: SkillResponse '404': description: Skill not found content: application/json: schema: type: object properties: error: type: string required: - error id: SkillError parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: slug required: true x-codeSamples: - lang: JavaScript source: >- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const skill = await client.skills.get('slug', { namespace: 'namespace' }); console.log(skill.id); put: operationId: putSkills:namespace:slug tags: - skills summary: Create or update a skill description: >- Idempotent endpoint to create or update a GitHub-backed skill. Send application/json with `gitUrl`. requestBody: required: true content: application/json: schema: vendor: zod responses: '200': description: Skill updated successfully content: application/json: schema: type: object properties: id: type: string namespace: type: string slug: type: string displayName: type: string description: type: string gitUrl: anyOf: - type: string - type: 'null' externalStars: type: number listed: type: boolean createdAt: type: string updatedAt: type: string required: - id - namespace - slug - displayName - description - gitUrl - externalStars - listed - createdAt - updatedAt id: PutSkillResponse '201': description: Skill created successfully content: application/json: schema: type: object properties: id: type: string namespace: type: string slug: type: string displayName: type: string description: type: string gitUrl: anyOf: - type: string - type: 'null' externalStars: type: number listed: type: boolean createdAt: type: string updatedAt: type: string required: - id - namespace - slug - displayName - description - gitUrl - externalStars - listed - createdAt - updatedAt id: PutSkillResponse '400': description: Invalid request content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError '403': description: Forbidden - user does not own the namespace content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError '404': description: Namespace not found or SKILL.md not found content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError '409': description: Git URL already claimed by another skill content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError '422': description: SKILL.md validation error content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: slug required: true x-codeSamples: - lang: JavaScript source: |- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const response = await client.skills.set('slug', { namespace: 'namespace', body: {}, }); console.log(response.id); delete: operationId: deleteSkills:namespace:slug tags: - skills summary: Delete a skill description: >- Delete a skill by namespace and slug. Requires ownership of the namespace. responses: '200': description: Skill deleted successfully content: application/json: schema: type: object properties: success: type: boolean qualifiedName: type: string required: - success - qualifiedName id: DeleteSkillResponse '403': description: Forbidden - user does not own the namespace content: application/json: schema: type: object properties: error: type: string required: - error id: SkillError '404': description: Skill not found content: application/json: schema: type: object properties: error: type: string required: - error id: SkillError parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: slug required: true x-codeSamples: - lang: JavaScript source: >- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const skill = await client.skills.delete('slug', { namespace: 'namespace' }); console.log(skill.qualifiedName); /skills/{namespace}/{slug}/download: get: operationId: getSkills:namespace:slugDownload tags: - skills summary: Download skill bundle description: Download a ZIP bundle containing all skill files. responses: '200': description: Skill ZIP file content: application/zip: schema: type: string format: binary '404': description: Skill not found content: application/json: schema: type: object properties: error: type: string required: - error id: SkillError parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: slug required: true x-hidden: true x-codeSamples: - lang: JavaScript source: >- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const response = await client.skills.download('slug', { namespace: 'namespace' }); console.log(response); const content = await response.blob(); console.log(content); /skills/{namespace}/{slug}/sync: post: operationId: postSkills:namespace:slugSync tags: - skills summary: Sync skill metadata from GitHub (deprecated) description: >- **Deprecated:** Use PUT /skills/{namespace}/{slug} instead. Refetch SKILL.md and repository stars from GitHub and update the skill record. deprecated: true responses: '200': description: Skill synced successfully content: application/json: schema: type: object properties: id: type: string namespace: type: string slug: type: string displayName: type: string description: type: string externalStars: type: number gitUrl: type: string updatedAt: type: string required: - id - namespace - slug - displayName - description - externalStars - gitUrl - updatedAt id: SyncSkillResponse '403': description: Forbidden - user does not own the namespace content: application/json: schema: type: object properties: error: type: string required: - error id: SkillError '404': description: Skill not found content: application/json: schema: type: object properties: error: type: string required: - error id: SkillError '422': description: Validation error - SKILL.md invalid content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: slug required: true x-hidden: true x-codeSamples: - lang: JavaScript source: >- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const response = await client.skills.sync('slug', { namespace: 'namespace' }); console.log(response.id); /skills/{namespace}/{slug}/upload: put: operationId: putSkills:namespace:slugUpload tags: - skills summary: Upload a skill bundle description: >- Upload or replace a skill bundle via multipart/form-data with an `archive` file. requestBody: required: true content: multipart/form-data: schema: type: object properties: archive: type: string format: binary description: >- ZIP file upload containing a skill folder with SKILL.md and any scripts, references, or assets. required: - archive responses: '200': description: Skill updated successfully content: application/json: schema: type: object properties: id: type: string namespace: type: string slug: type: string displayName: type: string description: type: string gitUrl: anyOf: - type: string - type: 'null' externalStars: type: number listed: type: boolean createdAt: type: string updatedAt: type: string required: - id - namespace - slug - displayName - description - gitUrl - externalStars - listed - createdAt - updatedAt id: PutSkillResponse '201': description: Skill created successfully content: application/json: schema: type: object properties: id: type: string namespace: type: string slug: type: string displayName: type: string description: type: string gitUrl: anyOf: - type: string - type: 'null' externalStars: type: number listed: type: boolean createdAt: type: string updatedAt: type: string required: - id - namespace - slug - displayName - description - gitUrl - externalStars - listed - createdAt - updatedAt id: PutSkillResponse '400': description: Invalid request content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError '403': description: Forbidden - user does not own the namespace content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError '404': description: Namespace not found content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError '422': description: SKILL.md validation error content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError '502': description: Failed to store uploaded skill bundle content: application/json: schema: type: object properties: error: type: string code: type: string required: - error id: CreateSkillError parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: slug required: true x-hidden: true x-codeSamples: - lang: JavaScript source: |- import fs from 'fs'; import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const response = await client.skills.upload('slug', { namespace: 'namespace', archive: fs.createReadStream('path/to/file'), }); console.log(response.id); /tokens: post: operationId: postTokens requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTokenRequest' tags: - tokens summary: Create a service token description: >- Create a service token for machine-to-machine authentication. Accepts API key or bearer token. Optionally apply restrictions. responses: '200': description: Token created successfully content: application/json: schema: $ref: '#/components/schemas/CreateTokenResponse' '400': description: Bad request (invalid parameters) content: application/json: schema: $ref: '#/components/schemas/TokenError' '401': description: Unauthorized (missing or invalid credentials) content: application/json: schema: $ref: '#/components/schemas/TokenError' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/TokenError' x-codeSamples: - lang: JavaScript source: |- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const createTokenResponse = await client.tokens.create(); console.log(createTokenResponse.token); /namespaces: get: operationId: getNamespaces tags: - namespaces summary: Get user's namespaces or search namespaces description: >- When called without query params, returns the authenticated user's namespaces (backwards compatible). When query params are provided, searches public namespaces with pagination. Use ownerId to filter by owner, hasServers/hasSkills to filter by content, q for text search. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/NamespacesSearchResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/NamespacesError' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/NamespacesError' parameters: - in: query name: q schema: type: string description: Text search query (prefix match on name) - in: query name: ownerId schema: type: string description: Filter by owner ID - in: query name: hasServers schema: type: string enum: - '0' - '1' - 'true' - 'false' description: Filter namespaces with servers - in: query name: hasSkills schema: type: string enum: - '0' - '1' - 'true' - 'false' description: Filter namespaces with skills - in: query name: page schema: type: integer minimum: 1 maximum: 9007199254740991 - in: query name: pageSize schema: type: integer minimum: 1 maximum: 50 - in: query name: fields schema: type: string description: Comma-separated list of fields to include in response x-codeSamples: - lang: JavaScript source: >- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const namespaceListResponse of client.namespaces.list()) { console.log(namespaceListResponse.name); } post: operationId: postNamespaces tags: - namespaces summary: Create a new namespace with generated name description: >- Create a new namespace with a server-generated human-readable name, owned by the authenticated user responses: '201': description: Namespace created successfully content: application/json: schema: $ref: '#/components/schemas/CreateNamespaceResponse' '400': description: Bad request (user already has a namespace) content: application/json: schema: $ref: '#/components/schemas/NamespacesError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/NamespacesError' '403': description: Forbidden - missing namespaces:write permission content: application/json: schema: $ref: '#/components/schemas/NamespacesError' x-codeSamples: - lang: JavaScript source: |- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const namespace = await client.namespaces.create(); console.log(namespace.createdAt); /namespaces/{name}: put: operationId: putNamespaces:name parameters: - in: path name: name schema: type: string minLength: 3 maxLength: 39 required: true tags: - namespaces summary: Create a new namespace description: >- Create a new namespace owned by the authenticated user or an organization. This endpoint is idempotent - if the namespace already exists and is owned by the user/org, returns success. Pass organizationId in the request body to create an org-owned namespace. responses: '201': description: Namespace created successfully content: application/json: schema: $ref: '#/components/schemas/CreateNamespaceResponse' '400': description: Bad request (invalid name format or user already has a namespace) content: application/json: schema: $ref: '#/components/schemas/NamespacesError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/NamespacesError' '403': description: Forbidden - missing namespaces:write permission content: application/json: schema: $ref: '#/components/schemas/NamespacesError' '409': description: Conflict (namespace already exists) content: application/json: schema: $ref: '#/components/schemas/NamespacesError' x-codeSamples: - lang: JavaScript source: |- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const response = await client.namespaces.set('xxx'); console.log(response.createdAt); delete: operationId: deleteNamespaces:name parameters: - in: path name: name schema: type: string minLength: 3 maxLength: 39 required: true tags: - namespaces summary: Delete a namespace description: >- Delete a namespace owned by the authenticated user. The namespace must not contain any servers. Skills and connections in the namespace will be deleted automatically. responses: '200': description: Namespace deleted successfully content: application/json: schema: type: object properties: success: type: boolean name: type: string example: myorg required: - success - name id: DeleteNamespaceResponse '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/NamespacesError' '403': description: Forbidden - user does not own this namespace content: application/json: schema: $ref: '#/components/schemas/NamespacesError' '404': description: Namespace not found content: application/json: schema: $ref: '#/components/schemas/NamespacesError' '409': description: Conflict - namespace contains servers that must be deleted first content: application/json: schema: $ref: '#/components/schemas/NamespacesError' x-codeSamples: - lang: JavaScript source: |- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const namespace = await client.namespaces.delete('xxx'); console.log(namespace.name); /namespaces/{namespace}/servers/{server}: put: operationId: putNamespaces:namespaceServers:server parameters: - in: path name: server schema: type: string minLength: 3 maxLength: 39 required: true - schema: type: string in: path name: namespace required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateServerRequest' tags: - namespaces summary: Create a server under a namespace (deprecated) description: >- **Deprecated:** Use PUT /servers/{namespace}/{server} instead. Create a new server under the specified namespace. This endpoint is idempotent. deprecated: true responses: '201': description: Server created successfully content: application/json: schema: $ref: '#/components/schemas/CreateServerResponse' '400': description: Bad request (invalid name format) content: application/json: schema: $ref: '#/components/schemas/CreateServerError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/CreateServerError' '403': description: >- Forbidden (namespace not owned by user or missing servers:write permission) content: application/json: schema: $ref: '#/components/schemas/CreateServerError' '404': description: Namespace not found content: application/json: schema: $ref: '#/components/schemas/CreateServerError' x-codeSamples: - lang: JavaScript source: >- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const server = await client.namespaces.servers.create('xxx', { namespace: 'namespace' }); console.log(server.createdAt); /organizations/{orgId}/api-keys: post: operationId: postOrganizations:orgIdApi-keys tags: - organizations summary: Create a team API key description: Creates an API key owned by the organization. Requires admin role. responses: '201': description: API key created (key value only shown on creation) content: application/json: schema: $ref: '#/components/schemas/TeamApiKeyCreated' '400': description: Bad request content: application/json: schema: type: object properties: error: type: string required: - error id: OrganizationError '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string required: - error id: OrganizationError '403': description: Forbidden — user is not an admin content: application/json: schema: type: object properties: error: type: string required: - error id: OrganizationError requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTeamApiKeyBody' parameters: - schema: type: string in: path name: orgId required: true x-codeSamples: - lang: JavaScript source: >- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const apiKey = await client.organizations.apiKeys.create('orgId', { name: 'x' }); console.log(apiKey.id); get: operationId: getOrganizations:orgIdApi-keys tags: - organizations summary: List team API keys description: >- Returns all API keys belonging to the organization. Requires admin role. Key values are not included in the response. responses: '200': description: List of team API keys content: application/json: schema: type: object properties: apiKeys: type: array items: $ref: '#/components/schemas/TeamApiKey' required: - apiKeys $defs: TeamApiKey: $ref: '#/components/schemas/TeamApiKey' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string required: - error id: OrganizationError '403': description: Forbidden — user is not an admin content: application/json: schema: type: object properties: error: type: string required: - error id: OrganizationError parameters: - schema: type: string in: path name: orgId required: true x-codeSamples: - lang: JavaScript source: |- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const apiKeys = await client.organizations.apiKeys.list('orgId'); console.log(apiKeys.apiKeys); /organizations/{orgId}/api-keys/{keyId}: delete: operationId: deleteOrganizations:orgIdApi-keys:keyId tags: - organizations summary: Revoke a team API key description: Deletes an API key belonging to the organization. Requires admin role. responses: '200': description: API key revoked content: application/json: schema: type: object properties: success: type: boolean required: - success id: RevokeTeamApiKeyResponse '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string required: - error id: OrganizationError '403': description: Forbidden — user is not an admin content: application/json: schema: type: object properties: error: type: string required: - error id: OrganizationError '404': description: API key not found in this organization content: application/json: schema: type: object properties: error: type: string required: - error id: OrganizationError parameters: - schema: type: string in: path name: orgId required: true - schema: type: string in: path name: keyId required: true x-codeSamples: - lang: JavaScript source: >- import Smithery from '@smithery/api'; const client = new Smithery({ apiKey: process.env['SMITHERY_API_KEY'], // This is the default and can be omitted }); const apiKey = await client.organizations.apiKeys.delete('keyId', { orgId: 'orgId' }); console.log(apiKey.success); /connect/{namespace}: get: operationId: getSmithery.run:namespace tags: - connect summary: List connections description: >- List all connections in a namespace. Supports filtering by metadata using `metadata.{key}={value}` query params. responses: '200': description: List of connections content: application/json: schema: $ref: '#/components/schemas/ConnectionsListResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' parameters: - in: query name: limit schema: example: 50 type: integer minimum: 1 maximum: 100 description: Maximum number of items to return (default 100, max 100) - in: query name: cursor schema: type: string description: Pagination cursor from previous response's nextCursor - in: query name: name schema: type: string description: Filter by exact connection name - in: query name: mcpUrl schema: type: string description: Filter by exact MCP server URL - schema: type: string in: path name: namespace required: true post: operationId: postSmithery.run:namespace tags: - connect summary: Create connection description: >- Create a new MCP connection with an auto-generated ID. Requires API key and namespace ownership. requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateConnectionRequest' responses: '201': description: Connection created content: application/json: schema: $ref: '#/components/schemas/Connection' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' '404': description: Namespace not found or access denied content: application/json: schema: $ref: '#/components/schemas/Error' parameters: - schema: type: string in: path name: namespace required: true /connect/{namespace}/{connectionId}/.triggers: get: operationId: getSmithery.run:namespace:connectionId.triggers tags: - connect summary: List triggers description: List trigger types exposed by a connection. responses: '200': description: Trigger definitions content: application/json: schema: $ref: '#/components/schemas/TriggerDefinitionList' '404': description: Connection not found content: application/json: schema: $ref: '#/components/schemas/Error' parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: connectionId required: true /connect/{namespace}/{connectionId}/.triggers/{triggerName}: get: operationId: getSmithery.run:namespace:connectionId.triggers:triggerName tags: - connect summary: Get trigger description: Get the schema for a single trigger type. responses: '200': description: Trigger definition content: application/json: schema: $ref: '#/components/schemas/TriggerDefinition' '404': description: Trigger not found content: application/json: schema: $ref: '#/components/schemas/Error' parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: connectionId required: true - schema: type: string in: path name: triggerName required: true post: operationId: postSmithery.run:namespace:connectionId.triggers:triggerName tags: - connect summary: Subscribe to trigger description: >- Subscribe to (or refresh) a trigger. Supplying the same (params, delivery.url) refreshes the TTL and may rotate the secret. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTriggerRequest' responses: '200': description: Subscription created or refreshed content: application/json: schema: $ref: '#/components/schemas/TriggerSubscription' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' '404': description: Connection or trigger not found content: application/json: schema: $ref: '#/components/schemas/Error' parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: connectionId required: true - schema: type: string in: path name: triggerName required: true delete: operationId: deleteSmithery.run:namespace:connectionId.triggers:triggerName tags: - connect summary: Unsubscribe from trigger description: >- Unsubscribe by subscription key (params + delivery.url). Eager teardown — subscriptions also expire naturally on TTL. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeleteTriggerRequest' responses: '200': description: Subscription removed content: application/json: schema: $ref: '#/components/schemas/Success' '404': description: Subscription not found content: application/json: schema: $ref: '#/components/schemas/Error' parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: connectionId required: true - schema: type: string in: path name: triggerName required: true /connect/{namespace}/{connectionId}: get: operationId: getSmithery.run:namespace:connectionId tags: - connect summary: Get connection description: >- Get details for a specific connection. Requires service token with connections:read scope. responses: '200': description: Connection details content: application/json: schema: $ref: '#/components/schemas/Connection' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Connection not found content: application/json: schema: $ref: '#/components/schemas/Error' parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: connectionId required: true put: operationId: putSmithery.run:namespace:connectionId tags: - connect summary: Create or update connection description: >- Create or update an MCP connection with the given ID. mcpUrl is required when creating a new connection, but optional when updating. Returns 409 if a different mcpUrl is provided, except while the connection is input_required and the new URL keeps the same host and path. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpsertConnectionRequest' responses: '200': description: Connection updated content: application/json: schema: $ref: '#/components/schemas/Connection' '201': description: Connection created content: application/json: schema: $ref: '#/components/schemas/Connection' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' '404': description: Namespace not found or access denied content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: URL mismatch content: application/json: schema: $ref: '#/components/schemas/Error' parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: connectionId required: true delete: operationId: deleteSmithery.run:namespace:connectionId tags: - connect summary: Delete connection description: >- Delete a connection and terminate its MCP session. Requires API key and namespace ownership. responses: '200': description: Connection deleted content: application/json: schema: $ref: '#/components/schemas/Success' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Namespace or connection not found content: application/json: schema: $ref: '#/components/schemas/Error' parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: connectionId required: true /connect/{namespace}/.tools: get: operationId: getSmithery.run:namespace.tools tags: - connect summary: List tools across a namespace description: >- List tools for every connection in a namespace in one response. Each connection is wrapped in an envelope so a failure on one upstream doesn't fail the request. Skips connections in `auth_required`/`input_required` states without calling the upstream. responses: '200': description: Tools by connection content: application/json: schema: $ref: '#/components/schemas/LooseObject' parameters: - schema: type: string in: path name: namespace required: true /connect/{namespace}/{connectionId}/.tools: get: operationId: getSmithery.run:namespace:connectionId.tools tags: - connect summary: List tools description: List tools exposed by a connection. responses: '200': description: Tool list content: application/json: schema: $ref: '#/components/schemas/ToolList' '404': description: Connection not found content: application/json: schema: $ref: '#/components/schemas/Error' parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: connectionId required: true /connect/{namespace}/{connectionId}/.tools/{toolPath}: get: operationId: getSmithery.run:namespace:connectionId.tools:toolPath tags: - connect summary: Get tool description: Get one tool or list tools under a slash-separated category. responses: '200': description: Tool metadata or category listing content: application/json: schema: $ref: '#/components/schemas/ToolResponse' '404': description: Connection or tool not found content: application/json: schema: $ref: '#/components/schemas/Error' parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: connectionId required: true - schema: type: string in: path name: toolPath required: true post: operationId: postSmithery.run:namespace:connectionId.tools:toolPath tags: - connect summary: Call tool description: Invoke a tool with JSON arguments. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LooseObject' responses: '200': description: Tool result content: application/json: schema: $ref: '#/components/schemas/LooseObject' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' '404': description: Connection not found content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Tool error content: application/json: schema: $ref: '#/components/schemas/Error' parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: connectionId required: true - schema: type: string in: path name: toolPath required: true