Skip to main content
The Empuls MCP server lets external AI assistants — Claude, ChatGPT, Codex, Cursor, Gemini CLI, and any other client that speaks the Model Context Protocol — act on your Empuls tenant. Once connected, you can ask your assistant to give an award, post a birthday wish, pull a redemption report, or look up your org hierarchy, and it calls Empuls as you, with your own role and permissions. Everything an assistant can do through MCP, you can already do in the Empuls web app. The MCP server just lets an AI client do it for you through natural language.
MCP is rolling out to pilot tenants. The Allow MCP admin setting only appears if your tenant is enabled for the pilot. Contact your Empuls representative to join.

​
How it works

The MCP server runs at a fixed path on your Empuls tenant:
When an MCP client connects, it:
  1. Discovers the server’s OAuth 2.1 metadata at /.well-known/oauth-protected-resource and /.well-known/openid-configuration.
  2. Registers itself dynamically as an OAuth client (no manual client ID or secret to paste).
  3. Opens your browser so you can sign in to Empuls with your normal SSO.
  4. Receives a scoped access token and calls the MCP endpoint as you.
Every subsequent tool call runs under your Empuls identity, so the same role, group, and ACL rules that gate the web app also gate the assistant.

​
Bundled tools

The MCP server exposes a small, curated set of tools: redeem_points is the only tool that spends anything. It is marked as destructive so well-behaved clients ask you to approve each call, codes expire after five minutes, and only three code attempts are allowed per quote.

​
Turn Allow MCP on (Super Admin)

Before anyone in your tenant can connect an assistant, a Super Admin needs to turn MCP on.
1

Open AI Permissions

Go to Reports and Admin > AI Settings > AI Permissions.
2

Enable Allow MCP

Turn on the Allow MCP card. This is the enforcement flag — the MCP server refuses tool calls from tenants where it is off, even if a user has already completed the OAuth flow.
If you do not see the Allow MCP card, your tenant is not in the pilot. Contact your Empuls representative to enable it.

​
Share setup with your team

From the Allow MCP card, select Share setup to open a ready-to-paste guide for your colleagues. The modal shows two things and copies each with one click:
  • The tenant connector URL (https://<your-tenant>/chef/api/empuls/v1/mcp) for Claude, ChatGPT, Cursor, and Gemini.
  • The Claude Code install commands (/plugin marketplace add … and /plugin install empuls@empuls).
The URL is derived from the browser origin, so admins on different tenants get the correct address without any configuration.

​
Install the Empuls plugin — Claude Code

Empuls publishes a plugin bundle for Claude Code that pre-loads the skills and points the client at your tenant’s MCP URL. The bundle is served from your tenant, so you do not need GitHub access to install it.
1

Add the Empuls marketplace

In Claude Code, run:
2

Install the plugin

3

Sign in

The first tool call opens your browser for Empuls SSO. Approve the requested scopes to finish setup.

​
Connect other MCP clients

Any MCP-compatible client can connect to the same endpoint. Bundled skills only load in Claude and Codex; on ChatGPT, Cursor, Gemini, and other hosts you get the tools (empuls_graphql, whoami, read_skill, redeem_points), the server’s built-in instructions, and the read_skill tool for on-demand guidance.
  1. Open Settings > Apps & Connectors and turn on Developer mode.
  2. Choose Add an MCP server.
  3. Set the URL to https://<your-tenant>.xoxoday.com/chef/api/empuls/v1/mcp and complete the OAuth flow in your browser.
Available on ChatGPT Plus, Pro, Business, Enterprise, and Edu plans with Developer mode enabled.
An org owner adds Empuls once, then users in the org can use it without extra credentials.
  1. Go to Settings > Connectors > Add connector.
  2. Paste https://<your-tenant>.xoxoday.com/chef/api/empuls/v1/mcp.
  3. Complete OAuth as the org owner.
Install the plugin from the co-located Codex manifest, then open a new thread so Codex loads the skills. Codex does not template config values, so edit the manifest’s mcpServers.empuls.url and replace https://<your-empuls-tenant> with your actual tenant URL.
Any client that speaks MCP over HTTP with OAuth can connect. Point it at https://<your-tenant>.xoxoday.com/chef/api/empuls/v1/mcp and complete the browser OAuth flow.

​
What you can ask an assistant to do

Once connected, phrase requests in plain language. Some examples:
  • “Give Priya a Spot Award for closing the Q3 renewal, 500 points, with a citation about her follow-through.”
  • “Who has a birthday this week on my team? Post a wish to each of them.”
  • “Show me last month’s redemption report grouped by department.”
  • “Find everyone in Marketing who reports to Ravi.”
  • “Redeem 1000 points for an Amazon India voucher.” (Your assistant runs redeem_points, emails you a six-digit code, and only places the order after you paste the code back.)
The assistant picks the right skill, loads its guidance with read_skill, and calls the matching Empuls operation with empuls_graphql. The first time a user connects an MCP client, Empuls opens an AI connector consent screen at /ai-connector/consent. It shows:
  • The AI client’s name and logo (e.g. Claude, ChatGPT).
  • The Empuls account the user is currently signed in as.
  • The list of things the client will be allowed to do, derived from the user’s Empuls role. This list is read-only — the user cannot pick individual permissions.
  • Allow and Deny buttons.
Two special cases replace the permission list:
  • Tenant not enabled. If Allow MCP is off for the tenant, the screen shows “Your administrator has not enabled AI assistant access for your organisation.” and hides both buttons. The user has no path forward until an admin turns MCP on.
  • Role has no MCP permissions. If the user’s role does not grant any MCP scopes, the screen shows “Your Empuls role does not include any AI assistant permissions.” and the Allow button stays disabled.
Access follows the user’s role. If a Super Admin changes what the role can do, the assistant’s capabilities change with it on the next token refresh.

​
Manage connected users (Super Admin)

Under AI Settings, the Connected AI clients panel lists every user in your tenant who has connected an assistant. For each user you see: Revoke signs out every AI client that user has connected. One grant row backs all of a user’s MCP tokens, so revoking is not per-client — it cuts them all at once. The user can reconnect by going through the consent screen again. Ban revokes and additionally blocks the user from consenting again. Choose Unban to allow them to reconnect. Ban writes a marker server-side; if a client’s cached token has not yet expired, that client may keep working briefly until the token refresh fails.
Both actions require confirmation. Revoke and Ban are destructive — the confirmation dialog will not dismiss on a background click, only on Cancel or Escape.

​
Safety and scope

  • Runs as you. Every call uses your Empuls identity and ACL. An assistant cannot see reports, users, or budgets that you cannot see in the web app.
  • Bulk pulls are capped. The server rate-limits and caps queries that would exfiltrate large slices of personal data.
  • No secrets travel with the plugin. The only stored config is your tenant base URL. Tokens live in the client and refresh over OAuth.
  • Point spending needs a code. redeem_points will not place an order without the six-digit code the tenant emails you after initiate.

​
Troubleshooting the OAuth flow

If your client cannot connect, work through these steps in order:
  1. Reachability. Confirm https://<tenant>/chef/api/empuls/v1/mcp returns HTTP 401. A 401 means the server is up and requiring auth; a timeout or DNS error means a network problem.
  2. Discovery. Fetch https://<tenant>/chef/.well-known/oauth-protected-resource/chef/api/empuls/v1/mcp and https://<tenant>/chef/.well-known/openid-configuration. Both must return JSON. Missing metadata is a tenant configuration issue — contact your Empuls admin.
  3. Callback mismatch. If OAuth redirects and then returns redirect_uri_mismatch, the client sent a redirect_uri that was not registered. Check the client’s registered redirect URIs.
  4. Token refresh. If tools work initially and then stop after a few hours, the access token expired and refresh is failing. Re-run the OAuth flow from the client’s settings.
  5. ChatGPT connector cache. ChatGPT caches the OAuth config per connector. If you change the tenant URL, remove and re-add the connector to force a fresh discovery.
  • AI settings — enable AI features including Allow MCP.
  • Em copilot — the built-in AI assistant inside the Empuls dashboard.