Smithery Connect API

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 que

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