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

# Connect an AI Assistant to Lucca

> Give Claude, ChatGPT, Copilot, Cursor and other AI assistants access to Lucca through its MCP server.

> [!WARNING]
>
> The Lucca MCP server is in **beta** and may change without notice: tools may be added, renamed or removed,
> and their capabilities or required scopes may change.

Lucca exposes an [MCP](https://modelcontextprotocol.io) server. Your AI assistant connects to it with one URL:

```
https://{account}.ilucca.net/assistant/mcp
```

Replace `https://{account}.ilucca.net` with the address you use to log in to Lucca. See [URL & Environments](https://developers.luccasoftware.com/documentation/get-started/environments.md).

The assistant acts on your behalf: it can only see and do what your Lucca account can, within the permissions you grant it.

***

## Before You Start

You can only connect to your own account's MCP server (`{account}.ilucca.net`), and only if your role has the
**Connect an AI agent to the lucca MCP** permission. If it does not, ask your Lucca administrator.

> [accordion] For administrators: grant the permission
>
> 1. Click your avatar.
> 2. Under **Administration**, click **Settings**, then **Roles**.
> 3. Open the role of the users who need access, then turn on **Connect an AI agent to the lucca MCP**.
>
> ![User menu with Settings under Administration, then the Settings list with the Roles entry](https://mintcdn.com/lucca/xPuiJYcMrBO6YR6l/assets/images/mcp/admin-roles-light.svg?fit=max\&auto=format\&n=xPuiJYcMrBO6YR6l\&q=85\&s=039c82c4ec376a3a8e43eb17691508df)

***

## Supported Clients: Paste the URL

These clients register themselves with Lucca. Add the URL, and on first use your client opens a browser: log in, choose what the assistant may access, then click **Allow**.

> [accordion] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http lucca https://{account}.ilucca.net/assistant/mcp
> ```
>
> Then run `/mcp`, select **lucca** and choose **Authenticate**.

> [accordion] Claude (web, desktop, mobile)
>
> Go to **Settings** > **Connectors** > **Add custom connector**, paste the URL, then click **Connect**.

> [accordion] Codex
>
> ```bash theme={null}
> codex mcp add lucca --url "https://{account}.ilucca.net/assistant/mcp" --oauth-client-id "https://chatgpt.com/oauth/codex/client.json"
> ```

> [accordion] ChatGPT
>
> Go to **Plugins** > **+** > **Add custom MCP server**, then paste the URL.
>
> On a Business, Enterprise or Edu workspace, your ChatGPT admin may need to allow custom MCP servers.

> [accordion] VS Code, GitHub Copilot
>
> Open the command palette, run **MCP: Add Server**, choose **HTTP**, then paste the URL.

> [accordion] Zed
>
> Go to **Settings** > **AI** > **MCP Servers** > **Add Remote Server**, then paste the URL.

> [accordion] Goose
>
> Run `goose configure`, choose **Add Extension** > **Remote Extension (Streamable HTTP)**, then paste the URL.

> [accordion] Hermes Agent
>
> In `config.yaml`:
>
> ```yaml theme={null}
> mcp_servers:
>   lucca:
>     url: "https://{account}.ilucca.net/assistant/mcp"
>     auth: oauth
> ```
>
> Then run `hermes mcp login lucca`.

> [accordion] Grok
>
> Go to [grok.com/connectors](https://grok.com/connectors) > **New Connector** > **Custom**, then paste the URL.

On first connection, Lucca shows a consent screen. Turn off the tool groups you do not want, then click **Allow**.

![Lucca consent screen, listing tool groups with toggles and Allow and Refuse buttons](https://mintcdn.com/lucca/xPuiJYcMrBO6YR6l/assets/images/mcp/consent-screen-light.svg?fit=max\&auto=format\&n=xPuiJYcMrBO6YR6l\&q=85\&s=a4c12246061189bcd6c2d8e7fd2edf51)

Lucca consent screen (simplified)

***

## Other Clients: Register the Client in Lucca

Other clients, such as Cursor or Gemini CLI, need a client ID and secret. Create a personal client in Lucca, then give both to your tool.

**1. Open your account**

Click your avatar, then **My account**.

![Avatar menu with the My account entry](https://mintcdn.com/lucca/xPuiJYcMrBO6YR6l/assets/images/mcp/avatar-menu-light.svg?fit=max\&auto=format\&n=xPuiJYcMrBO6YR6l\&q=85\&s=5a0a0f46f46bf8db09987da04b2026cc)

**2. Manage connected AI**

Under **Connected AI**, click **Manage**.

![My Lucca account panel with the Connected AI section](https://mintcdn.com/lucca/xPuiJYcMrBO6YR6l/assets/images/mcp/my-account-light.svg?fit=max\&auto=format\&n=xPuiJYcMrBO6YR6l\&q=85\&s=cf36df8d02b1e58875ad04e9200d05bf)

**3. Add an AI agent**

Click **Add**. This panel also shows the MCP URL to copy.

![Manage connected AI panel with the MCP URL and the Add button](https://mintcdn.com/lucca/xPuiJYcMrBO6YR6l/assets/images/mcp/manage-connected-ai-light.svg?fit=max\&auto=format\&n=xPuiJYcMrBO6YR6l\&q=85\&s=260397a14e2acc8e16901e6da91b1a66)

**4. Describe the agent**

Fill in **Name**, **Redirect URI** (given by your tool, see [below](#client-configuration)) and **Scopes**, then click **Authorize**.
To pick a scope, type its name to filter the list, then press Enter.

The redirect URI must use `https`, or `http` on `localhost`.

![Authorize an AI agent form with Name, Redirect URI and Scopes fields](https://mintcdn.com/lucca/xPuiJYcMrBO6YR6l/assets/images/mcp/authorize-agent-light.svg?fit=max\&auto=format\&n=xPuiJYcMrBO6YR6l\&q=85\&s=0bfbd2373adbd8c97bea71aef84121d8)

**5. Copy the credentials**

Copy the **Client ID** and **Secret key** into your tool.

> [!WARNING]
>
> The secret key is shown only once. If you lose it, revoke the agent and add it again.

![AI secret key dialog showing the client ID and secret key](https://mintcdn.com/lucca/xPuiJYcMrBO6YR6l/assets/images/mcp/secret-key-light.svg?fit=max\&auto=format\&n=xPuiJYcMrBO6YR6l\&q=85\&s=de1059caff921e1a136f84f451ec6bce)

### Client Configuration

In `scopes`, list the scopes you selected in Lucca. The examples below only request `employees.readonly`.

> [tab] Cursor
>
> Redirect URI: `http://localhost:8787/callback`
>
> ```json mcp.json theme={null}
> {
>   "mcpServers": {
>     "lucca": {
>       "url": "https://{account}.ilucca.net/assistant/mcp",
>       "auth": {
>         "CLIENT_ID": "...",
>         "CLIENT_SECRET": "...",
>         "scopes": ["employees.readonly"]
>       }
>     }
>   }
> }
> ```

> [tab] Gemini CLI
>
> Redirect URI: `http://localhost:7777/oauth/callback`
>
> ```json settings.json theme={null}
> {
>   "mcpServers": {
>     "lucca": {
>       "httpUrl": "https://{account}.ilucca.net/assistant/mcp",
>       "oauth": {
>         "enabled": true,
>         "clientId": "...",
>         "clientSecret": "...",
>         "redirectUri": "http://localhost:7777/oauth/callback",
>         "scopes": ["employees.readonly"]
>       }
>     }
>   }
> }
> ```
>
> Then run `/mcp auth lucca`.

***

## Which Scopes to Pick

A tool is available only when the client holds all the scopes it needs.
Pick read-only scopes unless you want the assistant to make changes.

| Scope | Gives access to |
| :- | :- |
| `employees.readonly` | Employees, managers, teams, headcount |
| `employments.readonly` | Contracts, job titles, career history |
| `employee-attribute-definitions.readonly` | Employee fields |
| `departments.readonly`, `business-establishments.readonly`, `legal-entities.readonly`, `job-qualifications.readonly` | Organization |
| `leaves.readonly`, `leave-requests.readonly`, `working-time-arrangements.readonly` | Absences and working hours |
| `leave-requests.readwrite` | Creating leave requests |
| `files.readonly` | Documents |

See [MCP Tools](https://developers.luccasoftware.com/documentation/mcp/tools.md) for every tool, the scopes it needs, and the tools on their way. See also [OAuth scopes](https://developers.luccasoftware.com/api-reference/latest/oauth-scopes.md).

***

## Troubleshooting

| Problem | Fix |
| :- | :- |
| Lucca refuses the connection | Ask your administrator for the **Connect an AI agent to the lucca MCP** permission. |
| The client asks for a client ID, or fails to register | [Register it in Lucca](#other-clients-register-the-client-in-lucca). |
| Redirect URI mismatch | Register the exact URI your tool uses, port included. |
| Some tools are missing | Add the scopes they need: **Manage connected AI** > pencil icon. For Cursor or Gemini CLI, also update the configured `scopes` array and authenticate again. |
| Lost secret key | Revoke the agent and add it again. |


## Related topics

- [MCP Tools](https://developers.luccasoftware.com/documentation/mcp/tools.md)
- [URL & Environments](https://developers.luccasoftware.com/documentation/get-started/environments.md)
- [OAuth scopes](https://developers.luccasoftware.com/api-reference/latest/oauth-scopes.md)
- [Security Best Practices](https://developers.luccasoftware.com/documentation/security.md)