Keephub MCP Server

A standalone Model Context Protocol (MCP) server that enables Large Language Models to interact with the Keephub REST API. Built on @modelcontextprotocol/sdk with Streamable HTTP transport, it provides domain-specific tools and guided workflows for the Keephub ecosystem.

Table Of Contents

• Features

• Quick Start

• MCP Tool Catalog

• Architecture

• Configuration & Authentication

• Development

• Build & Production

Related MCP server: BookStack MCP Server

Features

• Secure Authentication: Utilizes AsyncLocalStorage to inject security context from HTTP request headers (Authorization, X-Base-Url). Tokens and credentials are never exposed as tool parameters to the LLM.

• Native HTTP Transport: Direct interaction with the Keephub REST API via KeephubClient utilizing native fetch(). No third-party API middleman is required.

• Structured Error Handling: Implements standardized API and MCP error structures to ensure clear, actionable feedback to the LLM.

• Health Check Endpoint: Exposes GET /health so hosting platforms (for example Railway) can verify service liveness.

• Domain-Specific Tools: Functionality is modularized into dedicated namespaces:

  • Content: Create, update, delete, approve, reject, and query content (news, events, forms, pages).

  • Tasks: Create and manage actionable tasks, task templates, approvals, progress, and statuses.

  • Users: Search and retrieve full user profiles by ID, login name, group, or organizational unit.

  • Orgchart: Traverse and navigate Keephub organizational structures (parents, children, ancestors).

  • Form Submissions: View form results, get submitter details, and update orgunit visibilities.

• Pre-configured Prompts (Skills): Provides built-in MCP prompts designed to guide the LLM through complex workflows (for example creating tasks, updating content, and navigating orgcharts).

Quick Start

1. Install dependencies:

npm install

2. Configure authentication via either request headers or environment variables:

• Headers: Authorization, X-Base-Url

• Env fallback: KEEPHUB_TOKEN, KEEPHUB_BASE_URL (optional PORT)

3. Start development server:

npm run dev

4. Verify health endpoint:

curl http://localhost:3000/health

MCP Tool Catalog

The server currently exposes 55 MCP tools, grouped by namespace.

Discovery (1)

• search_keephub_capabilities: Router/index tool that helps the LLM choose the right tools and workflow prompts.

Context (6)

• context_discoverCreateContext: Resolve current user identity and available orgunits/groups/content pools for create operations.

• context_getMyProfile: Fetch the authenticated user's full profile.

• context_getMyScopeIds: Fetch compact scope IDs (user, orgunits, groups, content pools).

• context_getContentPools: List available content pools.

• context_getGroups: List available groups.

• context_getOrgchartRoots: List root orgchart nodes.

Content (12)

• content_create: Create content (news, event, form, manual, faq, training).

• content_updateById: Update content by ID.

• content_delete: Delete content by ID.

• content_getById: Get content by ID.

• content_findByContentPool: Find content by content pool.

• content_findByGroup: Find content by group.

• content_findByOrgunit: Find content by orgunit.

• content_findMyCandidates: Find compact candidate content items in current user scope.

• content_getEditableSummary: Get compact editable summary of content.

• content_getApprovalState: Get compact approval-state summary of content.

• content_approveContent: Approve pending content.

• content_rejectContent: Reject pending content.

Tasks (19)

• task_createTask: Create a task template.

• task_updateTask: Update task template in place (non-destructive merge flow).

• task_deleteTask: Delete task template.

• task_getTask: Get task template by ID.

• task_getTaskInstance: Get task instance by ID.

• task_getEditableSummary: Get compact editable summary for task template.

• task_findMyCandidates: Find compact candidate task templates for current user scope.

• task_getTaskByOrgunit: Find task templates by orgunit.

• task_getTaskProgress: Get completion progress for task template.

• task_getTaskStatusCounts: Get status counts for task template.

• task_getTemplateByTask: Get originating task template for a task instance.

• task_getMyAssignedTasks: List task instances assigned to current user.

• task_getMyTasksAwaitingApproval: List current user's own tasks awaiting approval.

• task_getMyPendingApprovals: List task instances awaiting current user's approval.

• task_getApprovalState: Get compact approval-state summary for task instance.

• task_normalizeUrls: Normalize Keephub task template/task instance URLs.

• task_approveTask: Approve pending task instance.

• task_approveAllPendingByTemplate: Bulk-approve pending task instances for a template.

• task_rejectTask: Reject pending task instance.

Users (5)

• user_getById: Get user by ID.

• user_findByName: Find users by display name.

• user_findByLoginName: Find user by login name.

• user_findByGroup: Find users by group.

• user_findByOrgunit: Find users by orgunit.

Orgchart (4)

• orgchart_getById: Get orgunit by ID.

• orgchart_getParent: Get parent orgunit.

• orgchart_getChildren: Get child orgunits.

• orgchart_getAncestors: Get ancestor orgunits.

Form Submissions (8)

• formSubmission_findByForm: Find form submissions by form content ID.

• formSubmission_getFormSubmission: Get form submission by ID.

• formSubmission_getEditContext: Get compact edit context for a submission.

• formSubmission_getSubmissionOrgunits: Get submission visibility orgunits.

• formSubmission_updateSubmissionOrgunits: Update submission visibility orgunits.

• formSubmission_getSubmitterDetails: Get submitter details for submission.

• formSubmission_calculateResponseDuration: Calculate submission response duration.

• formSubmission_findOneBySubmitterName: Find one recent submission by submitter name.

Tool Reference (Purpose + Key Inputs)

Discovery

Context

Content

Tasks

Users

Orgchart

Form Submissions

Prompt-Guided Workflows

In addition to tools, the server also registers MCP prompts (skills) for complex, multi-step flows such as content creation/updating, task template creation, orgchart navigation, rejection handling, and form submission orgunit updates.

Architecture

• src/mcp/setup.ts: Main MCP server configuration; registers all tools and prompts.

• src/mcp/tools/*.ts: Domain-specific MCP tool handlers.

• src/mcp/prompts/*.ts: Guided multi-step workflows (skills).

• src/mcp/auth.ts: AsyncLocalStorage-based auth context propagation.

• src/lib/keephubClient.ts: Fetch-based Keephub REST API client.

Configuration & Authentication

The MCP server uses AsyncLocalStorage to securely handle credentials. Credentials can be provided either through HTTP request headers (best for per-request multi-tenant usage) or through environment variables (best for local or single-tenant deployment).

1. HTTP Headers

• Authorization: Keephub bearer token (for example Bearer YOUR_TOKEN)

• X-Base-Url: Base API URL for the Keephub instance

2. Environment Variables (Fallback)

If headers are not provided, the server falls back to these environment variables:

• KEEPHUB_TOKEN: Bearer token

• KEEPHUB_BASE_URL: Base API URL (for example https://api.keephub.io)

• PORT: Optional listen port (default 3000)

You can place these values in a .env file for local development.

Development

Install dependencies:

npm install

Run the development server:

npm run dev

Health check (local):

curl http://localhost:3000/health

Build & Production

Compile the project for production:

npm run build

Start the production server:

npm run start