OnboardingHub OnboardingHub

MCP Integration

OnboardingHub provides a Model Context Protocol (MCP) server that lets AI assistants interact with your workspace. Use it with Claude Desktop, Cursor, or any MCP-compatible client.

The server requires the api-access entitlement on your workspace's plan.

Connecting from Claude Desktop (recommended)

Claude Desktop's config schema currently requires a local command, so we use the mcp-remote bridge — a small npm package that runs as a stdio server inside Claude Desktop and proxies requests to our remote HTTPS endpoint, handling the OAuth flow (sign-in, consent, token refresh) transparently.

Add this to your claude_desktop_config.json and restart Claude Desktop:

{
  "mcpServers": {
    "onboardinghub": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://onboarding-hub.com/mcp"
      ]
    }
  }
}

The first time you use a tool that talks to OnboardingHub, the bridge will:

  1. Open your browser to OnboardingHub's sign-in page.
  2. Ask you to pick a workspace (if you belong to more than one).
  3. Show you which scopes the client is requesting and ask you to Allow.

After you approve, you're done. The bridge caches your credentials in ~/.mcp-auth/ and refreshes the access token silently before it expires — you won't need to repeat the sign-in unless you explicitly disconnect or revoke. To force a re-authorization, delete the cache directory.

Other MCP clients

  • MCP Inspector, Cursor, Goose, and other clients that natively support remote MCP + OAuth 2.1 auto-discovery (RFC 8414 / 7591 / 9728) can connect with just the URL — no mcp-remote bridge needed. Check your client's docs for the exact config shape.
  • Anything that speaks JSON-RPC 2.0 over HTTP with a Bearer token can call /mcp directly — see "Connecting from scripts and automations" below.

Connecting from scripts and automations

For headless integrations (CI jobs, Zapier-style automations, custom scripts) where there's no browser, use a Custom Connection. Custom Connections issue a long-lived access token that you paste into your client's config.

  1. In your workspace, go to Settings → Integrations → API Keys.
  2. Click New API Key, name it, and pick the scopes you need.
  3. Copy the generated access token (shown once).
  4. Configure your client with the token as a Bearer header:
{
  "mcpServers": {
    "onboardinghub": {
      "url": "https://onboarding-hub.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Custom Connection tokens don't expire, so there's no refresh step — but they're a static secret. Treat them with the same care as any API key.

Available tools

Tools are filtered based on your token's scopes. Only tools whose required scope is present on your token are exposed.

Contact tools

Tool Description Required scope
list_contacts List contacts with filtering and pagination contacts:read
get_contact Get a contact by ID contacts:read
create_contact Create a new contact contacts:write
update_contact Update an existing contact contacts:write

Organisation tools

Tool Description Required scope
list_organisations List organisations with filtering organisations:read
get_organisation Get an organisation by ID organisations:read
create_organisation Create a new organisation organisations:write
update_organisation Update an existing organisation organisations:write

Enrollment tools

Tool Description Required scope
list_enrollments List enrollments with filtering enrollments:read
get_enrollment Get an enrollment by ID enrollments:read
create_enrollment Enroll a contact in a guide enrollments:write
update_enrollment Update enrollment status enrollments:write

Guide tools

Tool Description Required scope
list_guides List published guides guides:read
get_guide Get a guide with sections and steps guides:read

Webhook tools

Tool Description Required scope
list_webhook_endpoints List webhook endpoints webhooks:manage
create_webhook_endpoint Create a webhook endpoint webhooks:manage
update_webhook_endpoint Update a webhook endpoint webhooks:manage

Resources

The MCP server also exposes published guides as readable resources. With the guides:read scope, Claude and other AI assistants can read the full content of your guides (including section descriptions and step content).

Resources use the URI format: onboardinghub://guides/{guide_id}

Example usage

Once connected, you can ask your AI assistant things like:

  • "List all contacts in the Acme Corp organisation"
  • "Create a new contact with email [email protected]"
  • "Enroll contact abc123 in guide xyz789"
  • "Show me the enrollment progress for [email protected]"
  • "What guides do I have published?"
  • "Read the Getting Started guide"
  • "Create a webhook endpoint for enrollment.completed events"

Protocol details

  • Endpoint: POST https://onboarding-hub.com/mcp
  • Protocol: JSON-RPC 2.0 over HTTP
  • Transport: Stateless HTTP (no server-side sessions)
  • Server name: onboardinghub
  • Version: 1.0.0
  • The GET /mcp endpoint returns 405 Method Not Allowed (SSE streaming is not supported in stateless mode)
  • The DELETE /mcp endpoint returns 204 No Content (no sessions to clean up)

OAuth discovery (for client implementers)

A 401 from /mcp includes WWW-Authenticate: Bearer realm="OnboardingHub", resource_metadata="…" per RFC 6750, which is the entry point for discovery.

Next steps