openapi: 3.1.0 info: title: Smithery Connect API version: 1.0.0 description: Connect to MCP servers hosted on Smithery without managing OAuth, credentials, or sessions. Create stateless connections to any MCP server, execute MCP JSON-RPC, list/call tools and triggers, and manage subscriptions for trigger events. servers: - url: https://api.smithery.ai paths: /connect/{namespace}/.subscriptions: get: operationId: getSmithery.run:namespace.subscriptions tags: - connect summary: List namespace subscriptions description: List namespace-scoped trigger subscriptions for all connections in the namespace. responses: '200': description: Namespace subscriptions content: application/json: schema: $ref: '#/components/schemas/SubscriptionList' parameters: - schema: type: string in: path name: namespace required: true post: operationId: postSmithery.run:namespace.subscriptions tags: - connect summary: Create namespace subscription description: Create a namespace-scoped subscription that receives events from every connection in the namespace. responses: '200': description: Subscription created content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionResponse' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' parameters: - schema: type: string in: path name: namespace required: true /connect/{namespace}/.subscriptions/{subscriptionId}: delete: operationId: deleteSmithery.run:namespace.subscriptions:subscriptionId tags: - connect summary: Delete namespace subscription description: Delete a namespace-scoped trigger subscription. responses: '200': description: Subscription deleted 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: subscriptionId 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: Create trigger instance description: Create a trigger instance for a connection using the trigger's declared params. responses: '200': description: Trigger instance created content: application/json: schema: $ref: '#/components/schemas/TriggerInstance' '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 /connect/{namespace}/{connectionId}/.triggers/{triggerName}/{triggerId}: get: operationId: getSmithery.run:namespace:connectionId.triggers:triggerName:triggerId tags: - connect summary: Get trigger instance description: Get a specific trigger instance for a connection. responses: '200': description: Trigger instance content: application/json: schema: $ref: '#/components/schemas/TriggerInstance' '404': description: Trigger instance 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 - schema: type: string in: path name: triggerId required: true delete: operationId: deleteSmithery.run:namespace:connectionId.triggers:triggerName:triggerId tags: - connect summary: Delete trigger instance description: Delete a trigger instance and deregister its upstream webhook. responses: '200': description: Trigger instance deleted content: application/json: schema: $ref: '#/components/schemas/Success' '404': description: Trigger instance 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 - schema: type: string in: path name: triggerId required: true /connect/{namespace}/{connectionId}/.subscriptions: get: operationId: getSmithery.run:namespace:connectionId.subscriptions tags: - connect summary: List connection subscriptions description: List trigger subscriptions scoped to a single connection. responses: '200': description: Connection subscriptions content: application/json: schema: $ref: '#/components/schemas/SubscriptionList' '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 post: operationId: postSmithery.run:namespace:connectionId.subscriptions tags: - connect summary: Create connection subscription description: Create a connection-scoped subscription that receives events from one connection. responses: '200': description: Subscription created content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionResponse' '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' parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: connectionId required: true /connect/{namespace}/{connectionId}/.subscriptions/{subscriptionId}: delete: operationId: deleteSmithery.run:namespace:connectionId.subscriptions:subscriptionId tags: - connect summary: Delete connection subscription description: Delete a connection-scoped trigger subscription. responses: '200': description: Subscription deleted 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: subscriptionId required: true /connect/{namespace}: post: operationId: post:namespace tags: - connect summary: Create connection description: Create a new MCP connection with an auto-generated ID. Requires API key and namespace ownership. 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' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateConnectionRequest' parameters: - schema: type: string in: path name: namespace required: true get: operationId: get: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 /connect/{namespace}/{connectionId}: put: operationId: put: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. 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' requestBody: content: application/json: schema: $ref: '#/components/schemas/UpsertConnectionRequest' parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: connectionId required: true get: operationId: get: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 delete: operationId: delete: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}/{connectionId}/mcp: post: operationId: post:namespace:connectionIdMcp tags: - connect.mcp summary: MCP endpoint description: "Stateless MCP endpoint using Streamable HTTP transport. Accepts JSON-RPC requests and notifications. Session management is handled internally by Connect\u2014clients should not send\ \ mcp-session-id headers. Requires service token with mcp scope." responses: '200': description: JSON-RPC response content: application/json: schema: $ref: '#/components/schemas/JsonRpcResponse' '202': description: Notification accepted '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/JsonRpcError' '401': description: Authorization required content: application/json: schema: $ref: '#/components/schemas/AuthRequiredError' '404': description: Connection not found content: application/json: schema: $ref: '#/components/schemas/JsonRpcError' '405': description: Method not allowed (stateless mode) '409': description: Input required content: application/json: schema: $ref: '#/components/schemas/InputRequiredError' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/JsonRpcError' '502': description: Upstream error content: application/json: schema: $ref: '#/components/schemas/JsonRpcError' parameters: - schema: type: string in: path name: namespace required: true - schema: type: string in: path name: connectionId required: true 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. 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. 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. type: integer minimum: 10 maximum: 500 fields: description: Comma-separated list of fields to include in response type: string 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, 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, 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 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 \u2014 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 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' CreateTriggerRequest: type: object properties: params: default: {} description: Trigger-specific parameters defined by the trigger inputSchema $ref: '#/components/schemas/LooseObject' required: - params additionalProperties: false TriggerInstance: type: object properties: id: type: string description: Stable trigger instance id generated by Smithery example: trg_01HW1234567890 name: type: string description: Trigger name example: page.updated connection_id: type: string description: Connection id the trigger belongs to example: notion params: description: Trigger instance parameters $ref: '#/components/schemas/LooseObject' created_at: type: string description: ISO 8601 timestamp example: '2026-04-22T12:00:00.000Z' required: - id - name - connection_id - params - created_at additionalProperties: false Subscription: type: object properties: id: type: string description: Stable subscription id generated by Smithery example: sub_01HW1234567890 url: type: string format: uri description: Destination URL for webhook deliveries example: https://my-app.example.com/events connection_id: anyOf: - type: string - type: 'null' description: Connection scope. Null for namespace-wide subscriptions. example: notion created_at: type: string description: ISO 8601 timestamp example: '2026-04-22T12:00:00.000Z' required: - id - url - connection_id - created_at additionalProperties: false SubscriptionList: type: array items: $ref: '#/components/schemas/Subscription' CreateSubscriptionRequest: type: object properties: url: type: string format: uri description: HTTPS webhook destination example: https://my-app.example.com/events required: - url additionalProperties: false CreateSubscriptionResponse: type: object properties: id: type: string description: Stable subscription id generated by Smithery example: sub_01HW1234567890 url: type: string format: uri description: Destination URL for webhook deliveries example: https://my-app.example.com/events connection_id: anyOf: - type: string - type: 'null' description: Connection scope. Null for namespace-wide subscriptions. example: notion created_at: type: string description: ISO 8601 timestamp example: '2026-04-22T12:00:00.000Z' secret: type: string description: Webhook signing secret. Returned only once at creation time. example: whsec_0123456789abcdef required: - id - url - connection_id - created_at - secret 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