HandbookHub MCP

npx add-mcp 'https://api.handbookhub.com/mcp'

Your company handbook, in your AI tools.

Developer documentationMCP

Table of Contents

Connect your assistant to saved policies. Search the right handbook, read the source, and cite it in an answer. For direct HTTP access, see the API documentation. Read why we built handbook MCP and an API.

Connect your first client

Available with Live Handbook, its free trial, and the two weeks of Live Handbook that come with a one-time Handbook purchase.

MCP server endpoint https://api.handbookhub.com/mcp

Documentation https://handbookhub.com/mcp

1. As the organization owner, open Settings → API access.
2. Create a token named for the client, such as “Cursor — engineering”. Select its handbooks and expiry.
3. Copy the secret once and store it securely. Use a separate token for each integration.
4. Configure a client below, then ask it to find a policy and read its source page.

Send the token in the Authorization: Bearer YOUR_API_TOKEN header. Existing API tokens work with MCP using the same permissions. Registered OAuth clients can also offer account linking: sign in as the organization owner, select handbooks, and approve read access.

Cursor

Set HANDBOOKHUB_API_TOKEN in the environment used to launch Cursor. Add this entry to your personal ~/.cursor/mcp.json, merging it with any existing servers.

{
  "mcpServers": {
    "handbookhub": {
      "url": "https://api.handbookhub.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:HANDBOOKHUB_API_TOKEN}"
      }
    }
  }
}

Restart Cursor after changing its environment. Run Cursor Settings: Tools & MCPs, enable the HandbookHub source if it is disabled, and confirm that it exposes four tools. Remote servers use environment interpolation; Cursor’s envFile option is for local stdio servers.

Cursor configuration reference

VS Code

Run MCP: Open User Configuration and merge this configuration into the VS Code user-profile file. VS Code prompts for the secret without putting it in the configuration.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "handbookhub-token",
      "description": "HandbookHub API token",
      "password": true
    }
  ],
  "servers": {
    "handbookhub": {
      "type": "http",
      "url": "https://api.handbookhub.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:handbookhub-token}"
      }
    }
  }
}

Start the server and approve trust when prompted. These servers and inputs settings target VS Code’s profile configuration. Copilot harness configurations use a different format and do not support this interactive input flow.

VS Code configuration reference

MCP Inspector

Run the official Inspector locally:

npx @modelcontextprotocol/inspector@2.11.0

Select Streamable HTTP, enter the server endpoint, and add an Authorization header containing Bearer YOUR_API_TOKEN. Connect, list tools, and run a search. Use a disposable, narrowly scoped token for testing and revoke it afterward.

Inspector is a separate local debugging tool. This documentation page does not accept tokens or make live requests.

Four read-only tools

Start with search, then read the relevant page before answering. Results include source URLs for citations; opening those URLs requires the reader’s normal HandbookHub access.

list_handbooks

Returns a paginated list of authorized handbooks with IDs, names, source URLs, and timestamps. meta.nextCursor contains the cursor for the next page, or null when no more results are available.

Input	Requirement
cursor	Optional · string
limit	Optional · integer · maximum 100

Example arguments

{
  "limit": 25
}

Example structured result

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Employee handbook",
      "url": "https://handbookhub.com/app/h/employee-handbook",
      "createdAt": null,
      "updatedAt": "2026-10-15T12:00:00.000Z"
    }
  ],
  "meta": {
    "nextCursor": null
  }
}

get_handbook

Returns metadata and the current nested page structure for an authorized handbook, including page IDs, titles, and slugs. Page content is not included.

Input	Requirement
handbookId	Required · string

Example arguments

{
  "handbookId": "507f1f77bcf86cd799439011"
}

Example structured result

{
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Employee handbook",
    "url": "https://handbookhub.com/app/h/employee-handbook",
    "createdAt": null,
    "updatedAt": "2026-10-15T12:00:00.000Z",
    "pages": [
      {
        "id": "parental-leave",
        "title": "Parental leave",
        "slug": "parental-leave",
        "children": []
      }
    ]
  },
  "meta": {}
}

get_page

Returns the latest saved page from an authorized handbook as plain text, with its title, source URL, and last-updated timestamp.

Input	Requirement
handbookId	Required · string
pageId	Required · string

Example arguments

{
  "handbookId": "507f1f77bcf86cd799439011",
  "pageId": "parental-leave"
}

Example structured result

{
  "data": {
    "id": "parental-leave",
    "handbookId": "507f1f77bcf86cd799439011",
    "title": "Parental leave",
    "url": "https://handbookhub.com/app/h/employee-handbook/parental-leave",
    "updatedAt": "2026-10-15T12:00:00.000Z",
    "text": "Contact your People team to arrange parental leave."
  },
  "meta": {}
}

search_handbooks

Searches authorized handbooks using keyword, title, and semantic matching. Returns matching snippets, handbook and page IDs, source URLs, timestamps, and relevance scores. Semantic indexing may lag edits; meta.semanticAvailable=false indicates keyword/title fallback. No AI answer is generated.

Input	Requirement
query	Required · string · 2–1000 characters
handbookId	Optional · string
limit	Optional · integer · maximum 50

Example arguments

{
  "query": "parental leave",
  "limit": 10
}

Example structured result

{
  "data": [
    {
      "handbookId": "507f1f77bcf86cd799439011",
      "pageId": "parental-leave",
      "title": "Parental leave",
      "url": "https://handbookhub.com/app/h/employee-handbook/parental-leave",
      "updatedAt": "2026-10-15T12:00:00.000Z",
      "snippet": "Contact your People team to arrange parental leave.",
      "score": 1
    }
  ],
  "meta": {
    "semanticAvailable": true
  }
}

Handbook lists default to 25 results (maximum 100); pass meta.nextCursor back as cursor until it is null. Search defaults to 10 results (maximum 50). Results provide data and meta in structured content, plus a text representation. Page content is plain text.

Permissions and saved content

Tokens can read explicitly selected handbooks or all handbooks, including future ones. Private handbooks remain private. Tokens cannot edit content, manage accounts, retrieve signatures, or read uploaded source documents or revision history.

Saving publishes content to integrations. Unsaved changes are unavailable. Search combines titles, keywords, and semantic matching; semantic indexing can lag edits, but snippets come from current saved content. When semantic search is unavailable, meta.semanticAvailable is false and keyword/title search still works. HandbookHub does not generate an AI answer in this flow.

Token expiry defaults to 90 days, with 30 days, one year, and no expiry also available. Rotate by creating a replacement and revoking the old token. Permission changes and revocation take effect on subsequent calls. When plan access ends, valid tokens stop working until eligible access is restored.

Keep credentials on your server

Keep credentials out of source control, URLs, prompts, and logs. The connected assistant receives the handbook content you authorize it to retrieve.

Troubleshooting

• 401: check the Authorization header, token expiry, and revocation. Application login tokens do not work. For an OAuth connection, reconnect from your assistant and approve handbook access again.
• 403: check plan eligibility and, for browser-based development, the server’s allowed origins.
• Resource not found: confirm the token’s handbook selection and that the page still exists in its current structure.
• No tools: confirm the API hostname and /mcp endpoint, then restart the connection.
• Invalid parameters: follow the tool schema and omit organization IDs and unsupported arguments.
• 503: MCP may be disabled or a required dependency unavailable. Keep the request ID for support.

Compatibility

The server uses SDK 2.3.1 and Node adapter 2.1.1, with JSON responses over stateless Streamable HTTP. It supports legacy 2025 initialization alongside the 2026 protocol. Clients using account linking must be registered with HandbookHub.

Local verification used Cursor 3.24.18 and MCP Inspector 2.11.0 CLI for connection, discovery, search, page reads, and revoked-token rejection with synthetic content. VS Code 1.114.0 connected and discovered all four tools; its chat flow still requires verification with a signed-in Copilot account. Production HTTPS checks remain part of the release process.

Looking for REST endpoints? Read the API documentation.