Connect GitBook to Claude: Administer Spaces and Organization Data

If you need to connect GitBook to Claude to automate documentation updates, manage organization members, or handle change requests, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and GitBook's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting GitBook to ChatGPT or explore our broader architectural overview on connecting GitBook to AI Agents.

Giving a Large Language Model (LLM) read and write access to a structured documentation platform like GitBook is a specialized engineering challenge. You have to handle deeply nested resource hierarchies, parse complex content Abstract Syntax Trees (ASTs), and respect strict permission boundaries across organizations, sites, and spaces. Every time GitBook updates an endpoint or deprecates a field, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for GitBook, connect it natively to Claude, and execute complex documentation workflows using natural language.

The Engineering Reality of the GitBook API

A custom MCP server is a self-hosted integration layer that translates an LLM's tool calls into REST API requests. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against GitBook's API requires dealing with several domain-specific quirks.

If you decide to build a custom MCP server for GitBook, you own the entire API lifecycle. Here are the specific challenges you will face when wrapping GitBook endpoints for an AI agent:

Deeply Nested Resource Hierarchies GitBook's data model is highly relational and hierarchical. To get to a single page of content, an agent must often traverse Organizations -> Sites -> Spaces -> Pages. If you expose these raw endpoints without clear schema descriptions, the LLM will hallucinate space_id or organization_id values. A well-designed MCP server must explicitly guide the model to fetch organizations first, then spaces, and only then attempt to read or modify pages, passing the required IDs down the chain.

Content ASTs and Change Requests GitBook does not just store flat HTML or Markdown. It stores content as a complex Abstract Syntax Tree (AST) composed of document blocks (paragraphs, hints, code blocks, API methods). Giving an LLM raw write access to a live space is dangerous and often results in malformed ASTs that break the UI. Furthermore, GitBook uses a Change Request architecture for updates - similar to pull requests in Git. Your MCP server needs to expose the creation of Change Requests rather than direct page mutations, allowing human administrators to review the LLM's drafted changes before merging.

Strict Rate Limits and Error Handling GitBook enforces rate limits on its API. If an agent tries to paginate through hundreds of pages in a massive space too quickly, GitBook will return a 429 Too Many Requests status. It is critical to note that Truto does not retry, throttle, or apply backoff on rate limit errors automatically. When an upstream API returns HTTP 429, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (your MCP client or agent framework) is responsible for reading these headers and implementing its own retry and backoff logic.

Instead of building this infrastructure from scratch, you can use Truto. Truto derives tool definitions dynamically from the integration's resource configurations and documentation records, exposing GitBook's endpoints as ready-to-use, fully typed MCP tools.

How to Generate a GitBook MCP Server with Truto

Truto creates MCP servers dynamically scoped to a specific integrated account. You do not need to write server code, define JSON schemas manually, or manage authentication token lifecycles. There are two ways to generate a GitBook MCP server in Truto: via the UI or programmatically via the API.

Method 1: Via the Truto UI

If you are setting up an internal automation workflow for your own team, the UI is the fastest path.

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected GitBook instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure the server settings. You can restrict the server to specific methods (like read only) or specific tags (like content or admin).
5. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/abc123def456...). This URL contains a securely hashed token that authenticates the client and routes requests to the correct GitBook tenant.

Method 2: Via the Truto API

If you are building an AI product and need to provision GitBook MCP servers dynamically for your end-users, you use the Truto API. The API validates that tools are available, generates a secure token, and returns a ready-to-use URL.

Make a POST request to /integrated-account/:id/mcp:

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitBook Content Admin Server",
    "config": {
      "methods": ["read", "write"],
      "require_api_token_auth": false
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response will contain the unique URL you need to configure Claude:

{
  "id": "mcp_abc123",
  "name": "GitBook Content Admin Server",
  "config": {
    "methods": ["read", "write"]
  },
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Connecting the GitBook MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with your AI client. Because Truto handles the MCP protocol over HTTP (Server-Sent Events / POST), you simply point the client to the URL.

Method A: Via the Claude UI (Desktop or Web)

Anthropic and OpenAI are increasingly supporting direct custom connectors in their user interfaces.

For Claude Desktop/Web:

1. Open Claude and navigate to Settings -> Integrations -> Add MCP Server (or Connectors -> Add custom connector depending on your tier).
2. Give the server a descriptive name like "GitBook Admin".
3. Paste the Truto MCP URL.
4. Click Add.

Claude will immediately ping the server, execute the initialize handshake, and call tools/list to populate its context window with GitBook capabilities.

For ChatGPT (Developer Mode):

1. In ChatGPT, go to Settings -> Apps -> Advanced settings.
2. Enable Developer mode.
3. Under MCP servers / Custom connectors, click add.
4. Name the connector and paste the Truto MCP URL.

Method B: Via Manual Configuration File

If you are configuring Claude Desktop locally for development, you can modify the claude_desktop_config.json file. Because Truto's MCP servers communicate over HTTP, you will use the official @modelcontextprotocol/server-sse package to proxy the local stdio connection to Truto's remote SSE endpoint.

Open your config file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "gitbook": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_TRUTO_TOKEN"
      ]
    }
  }
}

Restart Claude Desktop. The agent is now wired directly into your GitBook instance.

Hero Tools for GitBook Administration

When the MCP server initializes, Truto dynamically derives tools from the GitBook integration's resource definitions. To prevent context overflow, Truto structures these tools logically. Here are the highest-leverage tools your agent will use to administer GitBook.

List All GitBook Spaces

Before an agent can read or update content, it must know which spaces exist. This tool retrieves a list of spaces belonging to an organization.

Tool name: list_all_git_book_spaces Required parameters: organization_id

"I need to update our internal handbook. First, fetch a list of all GitBook spaces in our primary organization so I can find the ID for the 'Engineering Handbook' space."

List All GitBook Pages

Once the agent has a space_id, it needs to traverse the page hierarchy to find specific documents. This tool returns the structural array of pages within a space.

Tool name: list_all_git_book_pages Required parameters: space_id

"Retrieve all pages for the Engineering Handbook space (ID: sp_123abc). I am looking for the page titled 'Deployment Runbook'."

Get Single GitBook Page by ID

This is the core content retrieval tool. It fetches the full AST and metadata for a specific page, allowing Claude to read and analyze existing documentation.

Tool name: get_single_git_book_page_by_id Required parameters: space_id, id

"Read the content of the 'Deployment Runbook' page (ID: pg_456def) in the Engineering Handbook space. Summarize the current deployment steps."

Create a GitBook Change Request

Instead of blindly overwriting live content, best practice dictates using Change Requests. This tool initiates a new draft environment where the agent can stage updates for human review.

Tool name: create_a_git_book_change_request Required parameters: space_id

"Create a new Change Request in the Engineering Handbook space with the title 'Update Deployment Runbook for Q4'. We will use this to stage our new Kubernetes deployment steps."

Update a GitBook Organization Member by ID

Beyond content, agents can manage users. This tool allows the modification of member roles and access levels within a GitBook organization.

Tool name: update_a_git_book_organization_member_by_id Required parameters: organization_id, id

"Update the organization member with ID usr_789ghi to have 'admin' privileges in our primary GitBook organization."

List All GitBook Space Permissions Users

For security audits, an agent can retrieve exactly who has explicit permission overrides on specific, sensitive spaces (like an executive playbook or HR space).

Tool name: list_all_git_book_space_permissions_users Required parameters: space_id

"Audit the user permissions for the 'HR Executive Policies' space. List every user who has direct access to this space."

These represent just a fraction of the available operations. For the complete inventory of tools, schemas, and resource definitions, visit the GitBook integration page.

Workflows in Action

Connecting tools is only the first step. The real value of an MCP server emerges when an LLM orchestrates these tools into autonomous, multi-step workflows. Here are two concrete examples of how personas leverage this setup.

Workflow 1: The Technical Writer's Automated Documentation Audit

A technical writer needs to ensure that a specific API endpoint's documentation is up to date based on a recent code change, and wants to stage the update for review without breaking the live docs.

"Find the 'Authentication' page in our 'API Reference' space. Read the current content. Draft a new Change Request that adds a section about our new OAuth 2.0 PKCE flow. Do not publish it - leave it as a change request for me to review."

Execution Steps:

1. list_all_git_book_organizations: The agent fetches the organization context.
2. list_all_git_book_spaces: The agent searches for the space named "API Reference" and extracts its space_id.
3. list_all_git_book_pages: Using the space_id, the agent scans the page tree to find the "Authentication" page and extracts its page_id.
4. get_single_git_book_page_by_id: The agent reads the current AST of the Authentication page to understand its structure.
5. create_a_git_book_change_request: The agent generates a new Change Request, staging the new PKCE instructions within the correct AST block format, ready for the writer's approval.

Result: The writer opens GitBook and sees a perfectly formatted Change Request titled "Update Authentication with OAuth 2.0 PKCE", completely bypassing the manual copy-pasting process.

Workflow 2: The IT Administrator's Access Audit

An IT administrator needs to execute a quarterly access review to ensure only authorized personnel have access to restricted operational spaces.

"Run an access audit on the 'Infra Ops' space. Get all users who have explicit permissions on this space, cross-reference their current roles in the main organization, and remove any pending invites for the organization that are older than 30 days."

Execution Steps:

1. list_all_git_book_spaces: The agent locates the "Infra Ops" space to get its ID.
2. list_all_git_book_space_permissions_users: The agent pulls the exact list of users with direct space access.
3. list_all_git_book_organization_members: The agent pulls the organization directory to cross-reference roles.
4. list_all_git_book_organization_invites: The agent retrieves pending invites.
5. delete_a_git_book_organization_invite_by_id: The agent loops through invites older than 30 days and revokes them.

Result: The IT admin receives a summarized report of space access and confirmation that stale invites have been purged, drastically reducing the time spent clicking through GitBook settings panels.

Security and Access Control

Giving an AI agent access to your corporate documentation and administrative settings requires strict governance. Truto's MCP architecture provides several layers of security to limit the blast radius of an autonomous agent:

• Method Filtering: When generating the MCP token, you can restrict the server to specific HTTP methods. Passing methods: ["read"] ensures the agent can only execute get and list operations (like reading pages or auditing users), completely preventing it from deleting organizations or altering content.
• Tag Filtering: You can restrict tools based on integration tags. By applying a filter like tags: ["content"], the agent will only see tools related to spaces and pages, blinding it to administrative endpoints like team or billing management.
• Expiration Controls (expires_at): You can set an exact ISO datetime for the MCP server to expire. Once the expires_at timestamp is reached, the server token is automatically destroyed in Truto's KV storage, immediately revoking the agent's access. This is ideal for granting an LLM temporary access to execute a specific audit.
• Enforced API Token Auth (require_api_token_auth): By default, possessing the MCP URL is enough to connect. For high-security environments, setting require_api_token_auth: true forces the MCP client to also pass a valid Truto API token in the Authorization header. This ensures that even if the MCP URL is leaked in a log file, unauthorized users cannot execute tools.

Final Thoughts

Connecting GitBook to Claude transforms static documentation platforms into dynamic, agent-operated knowledge bases. By utilizing a managed MCP server, engineering teams bypass the grueling work of parsing ASTs, handling pagination, and managing OAuth token refreshes. Instead, you get immediate, secure, and typed access to GitBook's complete API surface, allowing your agents to focus on high-value tasks like content reviews, automated change requests, and security audits.