> ## Documentation Index
> Fetch the complete documentation index at: https://help-empuls.xoxoday.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Empuls MCP server

> Connect Claude, ChatGPT, Codex, and other MCP-compatible AI assistants to your Empuls tenant so they can run recognitions, reports, and lookups on your behalf.

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.

<Info>
  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.
</Info>

## How it works

The MCP server runs at a fixed path on your Empuls tenant:

```
https://<your-tenant>.xoxoday.com/chef/api/empuls/v1/mcp
```

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:

| Tool | What it does |
| - | - |
| `whoami` | Returns the calling user's profile (name, email, department, manager) and company context (points name, currency, timezone, tenant URL). Read-only. |
| `read_skill` | Loads a named skill's procedural guidance plus the GraphQL operations it uses. Skills available: `recognition`, `celebrations`, `reports`, `user-management`, `redemption`, `documentation`. |
| `empuls_graphql` | Runs a named Empuls operation from the AI tools catalog — the skill tells the assistant which operation to run and with what arguments. |
| `redeem_points` | Spends the caller's own reward points in two steps: `initiate` prices the voucher and emails a six-digit confirmation code, then `confirm` places the order with the code the user provides. |

`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.

<Steps>
  <Step title="Open AI Permissions">
    Go to **Reports and Admin > AI Settings > AI Permissions**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  If you do not see the **Allow MCP** card, your tenant is not in the pilot. Contact your Empuls representative to enable it.
</Note>

## 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.

<Steps>
  <Step title="Add the Empuls marketplace">
    In Claude Code, run:

    ```bash theme={null}
    /plugin marketplace add https://<your-tenant>.xoxoday.com/chef/plugin/marketplace.json
    ```
  </Step>

  <Step title="Install the plugin">
    ```bash theme={null}
    /plugin install empuls@empuls
    ```
  </Step>

  <Step title="Sign in">
    The first tool call opens your browser for Empuls SSO. Approve the requested scopes to finish setup.
  </Step>
</Steps>

## 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.

<AccordionGroup>
  <Accordion title="ChatGPT (Developer Mode)">
    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.
  </Accordion>

  <Accordion title="Claude Team or Enterprise (org connector)">
    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.
  </Accordion>

  <Accordion title="Codex">
    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.
  </Accordion>

  <Accordion title="Cursor, Gemini CLI, VS Code, or other MCP-over-HTTP clients">
    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.
  </Accordion>
</AccordionGroup>

## 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 consent screen (end users)

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:

| Column | Meaning |
| - | - |
| User, Email | Who connected. |
| Status | **Active** (recent tool call), **Idle** (connected but quiet), **Revoked** (grant cut, can reconnect), or **Banned** (blocked from consenting again). |
| Last used | When the user's assistant last called Empuls, in the browser's locale. |
| Actions | **Revoke** and **Ban** / **Unban**. |

**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.

<Warning>
  Both actions require confirmation. Revoke and Ban are destructive — the confirmation dialog will not dismiss on a background click, only on **Cancel** or **Escape**.
</Warning>

## 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.

## Related

* [AI settings](/admin/ai/ai-settings) — enable AI features including Allow MCP.
* [Em copilot](/admin/ai/empuls-copilot) — the built-in AI assistant inside the Empuls dashboard.