Skip to content

AI Assistants (MCP)

Huddo includes an MCP (Model Context Protocol) server, so AI assistants like Claude can work in Huddo on your behalf. They can read and write wiki pages, catch up on what changed in a space, submit and vote on ideas, comment, search, and save links.

Authentication uses OAuth: when an assistant first connects, the user signs in with their normal Huddo account and approves access. The assistant then acts as that user — it can only see and change what they can.

The MCP server is served under your Huddo URL:

[HUDDO_URI]/mcp
e.g. https://connections.example.com/huddo/mcp

Requirements

  • Helm chart huddo-cp 3.2.1 or huddo 2.7.0 (or later). Both deploy the mcp service by default.
  • Huddo global.imageTag 2026-11-12 or later. Older tags have no mcp image.
  • A user service with public OAuth client support: Boards global.imageTag 2026-09-25 or later when Huddo shares the Boards user service (Add to an existing Boards install).
  • The MCP server must be reachable by the assistant. For Claude Code and other clients running inside your network, your normal Huddo URL is enough. For the claude.ai web connector, Huddo must be reachable from the internet.

1. Register the OAuth client

Add a huddo-mcp entry to OAUTH_CLIENTS on the user service. The HCL Connections and Kubernetes config files already include it:

user:
    env:
        OAUTH_CLIENTS: >
            [{"id":"huddo-mcp","redirectUrls":["http://localhost/callback","https://claude.ai/api/mcp/auth_callback"]}]
  • http://localhost/callback covers local MCP clients such as Claude Code and Claude Desktop. Any port on localhost is accepted at runtime (per RFC 8252), so no port needs to be configured.
  • https://claude.ai/api/mcp/auth_callback is only needed for the claude.ai web connector — remove it if Huddo is not reachable from the internet.
  • huddo-mcp is a public OAuth client: it has no secret, and the user service enforces PKCE on it.

Huddo alongside Boards

When Huddo shares the Boards user service, set OAUTH_CLIENTS in your Boards values, not the Huddo ones — Huddo deploys no user service of its own. OAUTH_CLIENTS is a single JSON array: if it already holds boards-mcp (or Zapier, Power Automate), add the huddo-mcp object to the existing array rather than defining the variable twice:

user:
    env:
        OAUTH_CLIENTS: >
            [{"id":"boards-mcp","redirectUrls":["http://localhost/callback"]},
             {"id":"huddo-mcp","redirectUrls":["http://localhost/callback","https://claude.ai/api/mcp/auth_callback"]}]

2. The MCP service

The charts enable mcp by default and route it for you: [HUDDO_URI]/mcp, plus the two OAuth discovery documents at the host root (see Front proxy). It reads only HUDDO_URI from global.env — it holds no database or storage credentials — so there is nothing else to configure.

To choose which groups of tools assistants see, set HUDDO_MCP_TOOLSETS (a comma list; unset means all of them):

mcp:
    env:
        # core, search, links, wikis, ideas, spaces, crossapp, discussions
        HUDDO_MCP_TOOLSETS: core,search,wikis,ideas,spaces,crossapp

To turn the MCP server off:

mcp:
    enabled: false

3. Front proxy

OAuth discovery documents are requested at the host root, outside /huddo. A front proxy that only forwards location /huddo (the setup in Reverse Proxy) must also forward these two paths — see MCP OAuth discovery:

/.well-known/oauth-authorization-server/huddo
/.well-known/oauth-protected-resource/huddo/mcp

They are path-inserted (they end in /huddo and /huddo/mcp), so they never collide with Boards' own discovery documents on the same host.

4. Upgrade and verify

Apply the changes with your usual helm upgrade command, then verify:

curl https://connections.example.com/.well-known/oauth-protected-resource/huddo/mcp

This should return a small JSON document whose resource is your [HUDDO_URI]/mcp. The MCP endpoint itself should answer an unauthenticated request with 401 and a WWW-Authenticate header:

curl -i https://connections.example.com/huddo/mcp

5. Connect an assistant

Claude Code:

claude mcp add --transport http --client-id huddo-mcp --scope user huddo https://connections.example.com/huddo/mcp

Then run /mcp inside Claude Code to sign in to Huddo.

claude.ai: add a custom connector with the URL [HUDDO_URI]/mcp and the OAuth client ID huddo-mcp, then sign in when prompted.

What assistants can do

Area For example
Orientation Who am I, what did I touch lately, a digest of my week across inbox, wikis and labs
Wikis Find, read and write pages (with a guard against overwriting someone else's edit), page history, review queues
Ideas Find labs and ideas, submit, update and vote on ideas, summarise a lab, turn an idea into a wiki page
Spaces Find, read, join and star spaces
Discussions Read and post comments on pages, ideas and spaces
Search and links Search across Huddo, save and find bookmarks, preview links
Create & delete Create wikis, pages, labs and spaces; delete what the user may delete in the UI

Every delete is permanent and asks for a confirmation the assistant must read from Huddo first (the exact name or title); the server's own permission checks still decide who may delete.

See the MCP Tool Reference for every tool, its parameters and what it returns.