Skip to content

AI Assistants (MCP)

Boards includes an optional MCP (Model Context Protocol) server, so AI assistants like Claude can work with your boards on your behalf — find cards, create tasks, update assignments, summarise activity and more. See the Boards Cloud MCP page for an overview of what assistants can do once connected.

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

The MCP server is served from your API URL:

[API_GATEWAY]/mcp
e.g. https://connections.example.com/api-boards/mcp

Requirements

  • Helm chart huddo-boards-cp 2.4.0 or huddo-boards 2.2.0 (or later)
  • global.imageTag 2026-09-25 or later (adds the boards-mcp image and public OAuth client support in the user service)
  • The MCP server must be reachable by the assistant. For Claude Code and other clients running inside your network, your normal Boards URL is enough. For the claude.ai web connector, your Boards deployment must be reachable from the internet.

1. Register the OAuth client

Add a boards-mcp entry to OAUTH_CLIENTS on the user service in your values yaml:

user:
    env:
        OAUTH_CLIENTS: >
            [{"id":"boards-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 — omit it if your deployment is not reachable from the internet.
  • boards-mcp is a public OAuth client: it has no secret, and the user service enforces PKCE on it.

Note

OAUTH_CLIENTS is a single JSON array. If you already define it (e.g. for Zapier or Power Automate), add the boards-mcp object to the existing array rather than defining the variable twice.

2. Enable the MCP service

a) For HCL Connections (huddo-boards-cp)

The chart provides the ingress routing (the /api-boards/mcp path and the OAuth discovery paths at the host root) — you only set the public URLs and the hostname:

mcp:
    enabled: true
    env:
        API_GATEWAY: https://connections.example.com/api-boards
        APP_URI: https://connections.example.com/boards
    ingress:
        hosts:
            - "connections.example.com"

Note

The mcp service deliberately does not inherit global.env (least privilege — it holds no Mongo/S3 credentials), so API_GATEWAY and APP_URI must be repeated in mcp.env even though they are already set in global.env.

b) For Kubernetes (huddo-boards)

Enable the service and configure its ingress. The example below matches the path-based install from the example boards.yaml (release name huddo-boards — the additionalPaths backends reference the <release-name>-mcp service):

mcp:
    enabled: true
    env:
        API_GATEWAY: https://example.com/api-boards
        APP_URI: https://example.com/boards
    ingress:
        enabled: true
        hosts:
            - example.com
        path: /api-boards/mcp
        pathType: Prefix
        traefik:
            stripPrefix:
                enabled: true
                prefix: /api-boards
        # OAuth discovery paths — served from the host root, not under /api-boards
        additionalPaths:
            - path: /.well-known/oauth-protected-resource
              pathType: Prefix
              backend:
                  service:
                      name: huddo-boards-mcp
                      port:
                          number: 80
            - path: /.well-known/oauth-authorization-server
              pathType: Exact
              backend:
                  service:
                      name: huddo-boards-mcp
                      port:
                          number: 80

If you use subdomains instead of paths (e.g. API_GATEWAY: https://boards-api.example.com), set hosts to the API hostname, use path: /mcp and omit the stripPrefix section.

3. Front proxy (context root)

The OAuth discovery endpoints (/.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server) are always requested at the host root, even when the API is deployed under a context root such as /api-boards. The Helm charts route them at the host root of the Kubernetes ingress, but if a front proxy (IHS/httpd or NGINX) sits in front of your Kubernetes cluster — as is typical for HCL Connections — it only forwards the paths it is told to, so the discovery paths must be added there too:

A front proxy that forwards the whole host to Kubernetes (e.g. the httpd New Domain setup) already forwards these paths and needs no change.

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

This should return a small JSON document pointing at your [API_GATEWAY]/mcp resource. The MCP endpoint itself should respond to an unauthenticated request with 401 and a WWW-Authenticate header:

curl -i https://connections.example.com/api-boards/mcp

5. Connect an assistant

Follow the Boards Cloud instructions, replacing the cloud URL with your own [API_GATEWAY]/mcp. For example, Claude Code:

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

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