Heyoo MCP Server

What is an MCP server?

MCP (Model Context Protocol) is an open standard for connecting AI applications to external tools and data. It gives your AI agent structured access to APIs so it can take actions on your behalf — like creating a campaign or pulling its results — using natural language.

What can the Heyoo MCP server do?

The Heyoo MCP server gives your AI agent native access to your workspace through a single integration. You can discover the workspaces you belong to, browse the building blocks of a campaign, create, update, or archive campaigns, and check what’s scheduled — all using natural language.

Workspaces — list the workspaces you can act in, so the agent knows where to work
Campaigns — list campaigns, fetch a single campaign with its tags, groups, resources, and content pillar, and create, update, or archive campaigns
Posts — list posts in a date range with their status, plus engagement totals (reactions, comments, shares, clicks) for posts that are already live, so you can answer questions like “which days in July does Dwight have posts scheduled, and what status are they in?” You see your own posts by default; workspace admins can look up specific colleagues, or pull every member’s posts in a single call
Analytics — pull a workspace’s performance for a date range: headline KPIs (engagement, followers gained, engagement rate, posts published, active contributors, reactions, comments, earned media value), each compared against the immediately preceding period, with an optional per-day series, posting heatmap, and weekday breakdown. Members see their own numbers; admins can scope to the whole workspace, a single member, or an employee group
Members — list a workspace’s members to find who to look up posts for (workspace-admin access only)
Reference data — list the tags, employee groups, and content pillars in a workspace to wire them into a campaign

As an example, you could ask your AI client to “draft a campaign for next week’s product launch, target the Sales group, and keep it as a draft” — and it will look up the group, create the campaign, and hand you back a link to review. Or “for July, which days does my colleague Dwight Schrute have posts scheduled, and what’s their status?” — and it will resolve the member and return the dates with each post’s status. As an admin you can also go wider: “show me every post scheduled across the team next week” pulls all members’ posts in one call.

The agent acts as you. A campaign tool call can only do what your workspace role allows, and publishing a campaign with a start date in the past sends emails and Slack messages to employees immediately. Review drafts before you ask the agent to publish.

How authentication works

Unlike the REST API, the MCP server does not use an hey_ API key. It authenticates over OAuth 2.1: the first time your client connects, it opens a browser window where you sign in to Heyoo and approve access. Your client then stores the resulting token and refreshes it automatically — there’s no key to copy or paste. The server advertises OAuth discovery metadata and supports Dynamic Client Registration, so any compliant MCP client can register itself and complete the flow without manual setup. Every tool call is authorized against your live workspace role, so the agent can never exceed what you’re allowed to do in the app. The agent is only offered the tools your role can use, so non-admins don’t see the admin-only tools (creating, updating, or archiving campaigns, listing members, or looking up other members’ posts).

How to use the MCP server

Heyoo’s MCP server runs over streamable HTTP at:

https://app.heyoo.ai/mcp

Most modern clients can connect to this URL directly and will trigger the OAuth sign-in flow for you. For clients that only speak stdio, mcp-remote bridges to the remote endpoint and handles the OAuth handshake.

MCP client integrations

Claude (web & desktop)
Claude Code
Cursor
mcp-remote

Open Settings → Connectors → Add custom connector, then paste the Heyoo MCP URL:

https://app.heyoo.ai/mcp

Claude opens a browser window to sign in to Heyoo and approve access. Once connected, the Heyoo tools appear in the connectors menu.

claude mcp add --transport http heyoo https://app.heyoo.ai/mcp

On first use, Claude Code opens your browser to complete the Heyoo OAuth sign-in.

Open the command palette and choose Cursor Settings → MCP → Add new global MCP server.

{
  "mcpServers": {
    "heyoo": {
      "url": "https://app.heyoo.ai/mcp"
    }
  }
}

For any stdio-only MCP client, bridge to the remote endpoint with mcp-remote. It opens a browser for the OAuth flow on first run.

{
  "mcpServers": {
    "heyoo": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.heyoo.ai/mcp"]
    }
  }
}

Working across multiple workspaces

When you belong to a single workspace, the agent acts there automatically. If you belong to several, the workspace-scoped tools (campaigns, posts, members, and reference data) accept an optional workspace argument (a workspace slug or name). Omit it and the tool returns the list of your workspaces so the agent can ask which one you mean — or just tell it up front: “in the Acme workspace, list the active campaigns.”

Start a session with “list my Heyoo workspaces” to let the agent confirm which workspace it’s working in before it creates anything.

Available tools

Tool	Description
`list_workspaces`	List the workspaces the authenticated user can act in.
`list_tags`	List a workspace’s tags (id, name, color) for use in campaigns.
`list_groups`	List a workspace’s employee groups, to target a campaign at specific groups.
`list_content_pillars`	List a workspace’s content pillars (id, title, color).
`list_campaigns`	List campaigns in a workspace, optionally including archived ones.
`get_campaign`	Fetch a single campaign with its tags, groups, resources, and content pillar.
`create_campaign`	Create a campaign. Defaults to a draft; only a name and destination URL are required.
`update_campaign`	Update a campaign’s fields or its tag and group assignments.
`archive_campaign`	Archive a campaign so it’s hidden by default.
`list_members`	List a workspace’s members (id, name, email, role). Workspace-admin access only.
`get_analytics`	Get a workspace’s performance KPIs for a date range (engagement, followers gained, engagement rate, posts published, active contributors, reactions, comments, earned media value), each with period-over-period deltas. Defaults to the last 30 days; pass `month` or `from`/`to`. Members see their own numbers; admins can narrow to a single `user` or an employee `groupId`. Set `includeBreakdown` for the per-day series, posting heatmap, and weekday distribution.
`list_posts`	List posts in a date range with their status, plus engagement totals (reactions, comments, shares, clicks) for posts that are already live. Defaults to your own posts; admins can pass `user` (one or more members’ name, email, or id) to look up colleagues, or `allMembers` to pull everyone’s posts in a single call. Filter by `month` or `from`/`to` and `status`.

Looking for direct HTTP access instead of an AI agent? See the REST API reference and API Keys.

​What is an MCP server?

​What can the Heyoo MCP server do?

​How authentication works

​How to use the MCP server

​MCP client integrations

​Working across multiple workspaces

​Available tools

What is an MCP server?

What can the Heyoo MCP server do?

How authentication works

How to use the MCP server

MCP client integrations

Working across multiple workspaces

Available tools