Set Up the Happeo MCP Server

🎯 Who this article is for: Happeo admins complete the initial setup. An organization admin in your AI assistant registers the connector. All users can then connect their own accounts and start using Happeo from within their AI assistant.

💼 Package requirements: Available to the Enterprise Package and any package with an API add-on.

🔒 Permissions: Creating the OAuth client requires Happeo admin access. Registering the connector in Claude, for example, requires Claude organization admin access. Individual users can connect their own accounts once the admin setup is complete.

🧪 Rollout status: The Happeo MCP server is currently in alpha production and is available for Claude. Support for other AI assistants is currently not available.

1. Overview

Your team's AI assistant becomes a live window into your intranet. Someone can type "what is our expense policy?" into Claude and get the answer from your company's actual documentation in seconds. They can ask what the parental leave policy is and get the answer pulled straight from the HR Hub page, without opening a separate tab. They can publish a post to a Happeo channel without leaving their AI workflow.

Model Context Protocol (MCP) is the technology that makes this possible: it lets AI assistants connect to other tools and services, including Happeo.

MCP inherits each user's existing Happeo permissions. Whatever someone can read or write in Happeo, they can read or write through the AI assistant. Whatever they cannot access in Happeo, they cannot access through the AI assistant either.

2. Use cases

• Drafting internal communications without copy-pasting context: Someone uses their AI assistant to write an all-hands update or team announcement. Instead of manually pulling in relevant policies, past decisions, or channel history, the AI retrieves that context directly from Happeo. The employee goes from brief to draft in one workflow.
• Onboarding new hires faster: A new employee asks their AI assistant onboarding questions on day one. The assistant searches Happeo and returns answers grounded in what the company has actually documented, without the new hire needing to know where to look or who to ask.
• Staying informed without switching apps: A content owner asks their AI assistant to summarize the latest posts in a specific channel, then immediately publishes a follow-up post to that channel. Two tasks, one workflow, no context switching.
• Surfacing decisions and past work: Someone working on a proposal asks their AI assistant to pull relevant previous projects, decisions, or documented processes from Happeo. The assistant surfaces what exists so the person can build on it rather than starting from scratch.

3. Before you begin

Before starting, confirm the following:

• A Happeo admin is available to create the connection in Happeo.
• Someone with admin access to your organization's AI assistant account is available to register Happeo in that tool.
• Anyone who wants to connect will need their own account with the AI assistant you're using (for example, a Claude account)

4. How to set up the Happeo MCP server

Part 1: Set up the connection in Happeo

Completed by a Happeo admin.

This part creates a secure link between Happeo and your AI assistant. The steps below are specific to Claude, currently the only AI assistant this setup supports. Support for other AI assistants is being evaluated individually, and instructions will be published here once an integration is confirmed and tested.

1. In Happeo, navigate to Admin Settings → API Management → OAuth Apps.
2. Click Create new OAuth App.
3. Enter the following details:

Next, click Create.

1. Under Redirect URIs (the web addresses your AI assistant uses to complete the sign-in process), add both of the following:
   1. https://claude.ai/api/mcp/auth_callback
   2. https://claude.com/api/mcp/auth_callback
2. Under Scopes (the list of actions you are allowing Happeo to share with the AI assistant), add all available options.
3. Under Client Secrets, set an expiration date for your connection password (or check Never expires) and click Create Secret.
4. Go to the Example usage tab and copy the Client ID (your connection ID) and Client Secret (your connection password). You will need both for Part 2.

💡 Tip: Keep the Client ID and Client Secret accessible. You will paste them into your AI assistant in Part 2.

Part 2: Register Happeo in your AI assistant

At this time, step-by-step setup instructions are available for Claude only. Happeo's MCP server is built on open standards, but support for additional AI assistants is being evaluated individually and is not guaranteed to arrive through this same MCP connection. Instructions will be published here once an integration is confirmed and tested.

Claude

Completed by someone with admin access to your organization's Claude account.

1. In Claude, go to Organization Settings → Connectors.
2. Click Add → Custom → Web.
3. Fill in the following details:

And then click Add. Happeo is now registered for your entire Claude organization.

🗒️ Note: If your Happeo environment uses a custom web address, replace app.happeo.com in the URL above with your organization's Happeo address. For example: https://connect.yourcompany.com/mcp. This is built to work the same way on a custom domain. If you hit anything unexpected, reach out to Happeo Support and we’ll help you sort it out.

Linking your own account (individual users)

Once Parts 1 and 2 are complete, each user links their own Happeo account. The steps vary slightly by AI assistant, but the process is the same: find Happeo in your settings, click Connect, and follow the sign-in steps to grant access. Your AI assistant confirms when the link is active.

Claude

1. Open your Connectors settings in Claude.
2. Find Happeo and click Connect.
3. Follow the sign-in steps to grant access.

5. Best practices

A few habits keep the connection secure and useful over time.

• Set an expiration date on your connection password: Rather than selecting Never expires, giving your connection password an end date limits the risk if it is ever lost or exposed. When it is due to expire, generate a new one in Happeo, update the details in your AI assistant, and delete the old one immediately.
• Ask in plain language: The connection is built to respond to natural questions. Encourage your team to ask the AI assistant the same things they would type into Happeo Search: "What is our remote work policy?", "Who works in the Helsinki office?", or "Summarize the latest posts in the kudos channel."
• Test before rolling out: After setup, try a few questions to make sure the AI assistant is returning the right results and respecting access levels before sharing the connection with the wider team.

6. Letting your team know

Once the connection is live and tested, share it with your team. A few things worth covering in your announcement:

• What it does in plain terms: Most people are not familiar with MCP. Skip the technical explanation and describe the outcome: they can now ask their AI assistant questions about the company and get answers from Happeo directly.
• How to get connected: Users need to link their own accounts before they can use it. Tell them where to go (Connectors settings in their AI assistant) and what to expect (a quick sign-in flow).
• What to try first: Give one or two example questions that match something your team actually looks up often. A concrete example is faster than a general explanation.
• What it does not do: Worth setting expectations — the AI assistant only acts when asked, and it can only access what each person already has permission to see in Happeo.

6. Frequently asked questions

Can I use an AI assistant other than Claude?

Happeo's MCP server is built on open standards, so in theory it can work with any AI assistant that supports MCP connections. In practice, Claude is currently the only AI assistant confirmed to work, and it's the only one with step-by-step setup instructions in this article. Support for other AI assistants is being evaluated individually, and may arrive as a separate, dedicated integration rather than through this same MCP connection.

Will my access in Happeo update automatically if my permissions change?

Yes. MCP inherits your permissions in full, and those permissions are always current. If your access in Happeo changes, the AI assistant respects those changes straight away. There is no need to reconnect.

Can I search content from other connected tools, like Google Drive or Jira, through my AI assistant?

Yes. If your organization has a federated search connector installed and enabled in Happeo, MCP exposes that connector as an additional search source. For example, if Gmail is connected, you can ask your AI assistant to search your Gmail through Happeo. Results are still limited to what you personally have permission to see.

Can the AI assistant take actions in Happeo on my behalf without me asking it to?

No. The AI assistant only takes action when you explicitly ask it to. That said, agent behavior can vary depending on the AI assistant you use. We recommend reviewing your AI assistant's settings to configure this to your preference.

Can the AI assistant take actions in other connected tools, like closing a ticket in Asana or Jira?

Not through this connection. MCP exposes tools such as search and post creation, and your AI assistant calls those tools when you ask it to. Taking actions inside other connected tools (for example, closing an Asana ticket) is a separate capability, and it is not yet generally available.

Can I create or publish pages through my AI assistant?

Not yet. Page creation and publishing through MCP isn't supported today, but it's on the roadmap. For now, create and publish pages directly in Happeo.

Can I report a knowledge gap through my AI assistant?

Yes. You can ask your AI assistant to create a knowledge gap, the same way you might flag missing or incorrect information elsewhere in Happeo. Knowledge gaps are not created automatically through MCP; they are only created when you ask.

Are MCP queries visible in Happeo's Search analytics or Knowledge Engine?

Not currently. Questions asked through your AI assistant are not tracked in Happeo's Search analytics and do not feed into Knowledge Engine's gap detection today.

Are there rate limits or usage caps on MCP?

No. MCP has no rate limits, the same as Happeo's other APIs. This is separate from any usage limits that apply to Happeo's own AI agents.

Can my IT or security team see logs of what was asked and retrieved through MCP?

No. Visibility is currently limited to Happeo's standard access logs. There is no separate log of the specific questions asked or answers retrieved through an AI assistant.

How do I disconnect my Happeo account from the AI assistant?

To disconnect, remove Happeo from your AI assistant's MCP configuration. There is currently no option to disconnect at the individual user level from within Happeo. See Troubleshooting below if you need to revoke a user's access urgently, for example during offboarding or after a compromised credential.

Is there a limit to how many users can connect?

No. Any number of users can connect, as long as each person has a Happeo account.

8. Troubleshooting

The connection password was lost or exposed

In Happeo, go to Admin Settings → API Management → OAuth Apps, generate a new connection password, update the details in your AI assistant, and delete the old one immediately.

Sign-in fails or shows a redirect error

Check that the correct web addresses for your AI assistant are added to the Happeo setup. For Claude, these are https://claude.ai/api/mcp/auth_callback and https://claude.com/api/mcp/auth_callback. A missing or mistyped address is the most common cause of this error.

A feature is not showing up in the AI assistant

Check that all available options were selected under Scopes when you created the connection in Happeo. If anything was missed, create a new connection with all options added and update the details in your AI assistant.

The Happeo address is not working

If your organization uses a custom Happeo web address, make sure it is entered correctly in the URL field, with /mcp at the end. For example: https://connect.yourcompany.com/mcp.

You need to revoke one user's access urgently (offboarding or a compromised credential)

There is currently no way for a Happeo admin to disconnect a single user's MCP access on their own. The only confirmed option today is to contact Happeo Support, who can disable the MCP connection for your entire organization on request. This removes access for every connected user, not just one person, so use it when the situation calls for an immediate, organization-wide response.