GitBook Site MCP Servers API

openapi: 3.2.0
info:
  title: GitBook Site MCP Servers API
  description: The GitBook API
  termsOfService: https://policies.gitbook.com
  contact:
    name: API Support
    url: https://gitbook.com/support
    email: support@gitbook.com
  version: 0.0.1-beta
servers:
- url: '{host}/v1'
  variables:
    host:
      default: https://api.gitbook.com
security:
- user: []
- user-internal: []
- user-staff: []
- integration: []
- integration-installation: []
tags:
- name: site-mcp-servers
  x-page-title: Site MCP servers
  x-page-description: Configure external MCP servers used by your site.
  x-parent: sites
  description: 'Manage Model Context Protocol (Mcp) servers used by your site.


    {% openapi-schemas spec="gitbook" schemas="SiteMcpServer" grouped="false" %}

    The SiteMcpServer object

    {% endopenapi-schemas %}'
paths:
  /orgs/{organizationId}/sites/{siteId}/mcp-servers:
    get:
      operationId: listSiteMcpServers
      summary: List all MCP servers configured for a site
      description: Returns a paginated list of Model Context Protocol (MCP) server configurations attached to the site. MCP servers expose tools and resources that the AI Assistant can call when helping site visitors find information. Use this to audit or manage the AI tool integrations available on a site.
      x-gitbook-mcp: true
      tags:
      - site-mcp-servers
      security:
      - user: []
      - oauth:
        - site:read
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/siteId'
      - $ref: '#/components/parameters/listPage'
      - $ref: '#/components/parameters/listLimit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/List'
                - type: object
                  required:
                  - items
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/SiteMcpServer'
    post:
      operationId: createSiteMcpServer
      summary: Add a new MCP server configuration to a site
      description: Registers a new Model Context Protocol (MCP) server with the site, providing its URL, transport type, request headers, and an optional conditional expression to control visibility per visitor. Once added, the MCP server's tools become available to the AI Assistant when helping visitors of this site.
      x-gitbook-mcp: true
      tags:
      - site-mcp-servers
      security:
      - user: []
      - oauth:
        - site:write
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/siteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  $ref: '#/components/schemas/SiteMcpServerName'
                url:
                  $ref: '#/components/schemas/URL'
                transport:
                  $ref: '#/components/schemas/SiteMcpServerTransport'
                headers:
                  $ref: '#/components/schemas/SiteMcpServerHeaders'
                condition:
                  description: Conditional expression used to evaluate whether the MCP server should be available to the site's visitor (should evaluate to a boolean). If set to null, the condition will be removed.
                  oneOf:
                  - $ref: '#/components/schemas/Expression'
                  - type: 'null'
              required:
              - name
              - url
              - headers
      responses:
        '201':
          description: MCP server created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteMcpServer'
  /orgs/{organizationId}/sites/{siteId}/mcp-servers/{siteMcpServerId}:
    get:
      operationId: getSiteMcpServerById
      summary: Get an MCP server configuration for a site by its ID
      description: Retrieves the configuration of a specific MCP server registered with the site. Use this to inspect an MCP server's details before updating or removing it.
      x-gitbook-mcp: true
      tags:
      - site-mcp-servers
      security:
      - user: []
      - oauth:
        - site:read
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/siteId'
      - $ref: '#/components/parameters/siteMcpServerId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteMcpServer'
    patch:
      operationId: updateSiteMcpServerById
      summary: Update an MCP server configuration for a site
      description: Modifies an existing MCP server's configuration. Only provided fields are updated; omitting a field leaves it unchanged. Set condition to null to remove it and make the MCP server available to all visitors.
      x-gitbook-mcp: true
      tags:
      - site-mcp-servers
      security:
      - user: []
      - oauth:
        - site:write
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/siteId'
      - $ref: '#/components/parameters/siteMcpServerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  $ref: '#/components/schemas/SiteMcpServerName'
                url:
                  type: string
                  format: uri
                  maxLength: 2048
                transport:
                  $ref: '#/components/schemas/SiteMcpServerTransport'
                headers:
                  $ref: '#/components/schemas/SiteMcpServerHeaders'
                condition:
                  description: Conditional expression used to evaluate whether the MCP server should be available to the site's visitor (should evaluate to a boolean). If not set, the condition will remain unchanged. If set to null, the condition will be removed.
                  oneOf:
                  - $ref: '#/components/schemas/Expression'
                  - type: 'null'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteMcpServer'
    delete:
      operationId: deleteSiteMcpServerById
      summary: Delete a site MCP server
      tags:
      - site-mcp-servers
      security:
      - user: []
      - oauth:
        - site:write
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/siteId'
      - $ref: '#/components/parameters/siteMcpServerId'
      responses:
        '204':
          description: MCP server did not exist
        '205':
          description: MCP server deleted
components:
  parameters:
    siteId:
      name: siteId
      in: path
      required: true
      description: The unique id of the site
      schema:
        type: string
    siteMcpServerId:
      name: siteMcpServerId
      in: path
      required: true
      description: The unique id of the MCP server
      schema:
        type: string
    listPage:
      name: page
      in: query
      description: Identifier of the page results to fetch.
      schema:
        type: string
    listLimit:
      name: limit
      in: query
      description: The number of results per page
      schema:
        type: number
        minimum: 0
        maximum: 1000
    organizationId:
      name: organizationId
      in: path
      required: true
      description: The unique id of the organization
      schema:
        $ref: '#/components/schemas/EntityId'
  schemas:
    Expression:
      type: string
      description: Expression to evaluate
      minLength: 0
      maxLength: 1024
    List:
      type: object
      properties:
        next:
          type: object
          properties:
            page:
              type: string
              description: Unique identifier to query the next results page
          required:
          - page
        count:
          type: number
          description: Total count of objects in the list
    SiteMcpServer:
      type: object
      properties:
        object:
          type: string
          enum:
          - site-mcp-server
        id:
          type: string
          description: Unique identifier for the MCP server
        name:
          $ref: '#/components/schemas/SiteMcpServerName'
        url:
          $ref: '#/components/schemas/URL'
        transport:
          $ref: '#/components/schemas/SiteMcpServerTransport'
        headers:
          $ref: '#/components/schemas/SiteMcpServerHeaders'
        condition:
          description: Conditional expression used to evaluate whether the MCP server should be available to the site's visitor.
          $ref: '#/components/schemas/Expression'
        urls:
          type: object
          description: URLs associated with the object
          properties:
            location:
              type: string
              description: URL of the MCP server in the API
              format: uri
          required:
          - location
      required:
      - object
      - id
      - name
      - url
      - transport
      - headers
      - urls
    EntityId:
      type: string
      pattern: ^[a-zA-Z0-9_-]+$
      description: A unique entity identifier
    URL:
      type: string
      format: uri
      maxLength: 2048
    SiteMcpServerName:
      type: string
      description: Name of the MCP server
      minLength: 1
      maxLength: 100
    SiteMcpServerTransport:
      type: string
      description: Transport protocol used to connect to the MCP server
      enum:
      - sse
      - http
      default: sse
    SiteMcpServerHeaders:
      type: object
      additionalProperties:
        type: string
        minLength: 1
        maxLength: 512
      description: HTTP headers sent with requests to this server
  securitySchemes:
    user:
      type: http
      scheme: bearer
    user-internal:
      type: http
      scheme: bearer
    user-staff:
      type: http
      scheme: bearer
    integration:
      type: http
      scheme: bearer
    integration-installation:
      type: http
      scheme: bearer
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://oauth.gitbook.com/authorize
          tokenUrl: https://oauth.gitbook.com/token
          scopes:
            user:read: Read your GitBook user profile.
            organization:read: Read the organizations you belong to, their settings and metadata, and their AI agent conversations.
            organization:write: Create organizations, and update organization settings and AI agent conversations.
            organization:members:read: Read organization members, teams, invites and link invites.
            organization:members:write: Manage organization members, teams, invites and link invites.
            organization:ask: Ask AI questions across an organization's content.
            organization:search: Search across an organization's content.
            space:read: Read spaces and their content, including pages, change requests and their reviews, comments, files and revision history.
            space:write: Create, update and delete spaces and their content, including change requests (create, edit, review), comments, and content imports and exports. Merging a change request also requires change-request:merge.
            space:permissions:read: Read the users and teams who have access to spaces and collections.
            space:permissions:write: Manage who has access to spaces and collections, including inviting users and teams.
            change-request:merge: Merge change requests, publishing their changes to the space. Creating, editing and reviewing change requests only requires space:write.
            site:read: Read sites and their settings, including navigation structure, linked spaces, customization, redirects, topics, AI configuration and documentation issues.
            site:write: Create, update and delete sites and their settings, including navigation structure (sections, linked spaces, external links), customization, redirects, topics and AI configuration.
            site:publish: Publish and unpublish sites, controlling their public exposure.
            site:permissions:read: Read the users and teams who have access to sites.
            site:permissions:write: Manage who has access to sites, including inviting users and teams.
            site:auth:read: Read how visitors authenticate on a site and its security configuration, including private share links.
            site:auth:write: Manage how visitors authenticate on a site and its security configuration, including private share links.
            site:insights:read: Read site analytics and insights, including the questions visitors asked Ask AI and the answers they received.
            site:ask: Ask AI questions across a site's content.
            site:search: Search across a site's content.
            integration:read: Read integrations, their status and where they are installed.
            integration:installations:read: Read integration installations and their configuration, which can include credentials for third-party services.
            integration:installations:write: Install and configure integrations on an organization, its spaces and its sites.
            integration:publish: Publish integrations, which can request their own permissions on your content, and route their events to a development tunnel.
            integration:delete: Unpublish integrations, permanently deleting them and every installation of them.
            openapi:read: Read OpenAPI specifications.
            openapi:write: Create, update and delete OpenAPI specifications.
x-provenance:
  method: harvested
  publisher: GitBook
  source: https://api.gitbook.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)