Connect an AI Assistant to Lucca

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

For administrators: grant the permission

Click your avatar.
Under Administration, click Settings, then Roles.
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

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.

Claude Code

claude mcp add --transport http lucca https://{account}.ilucca.net/assistant/mcp

Then run /mcp, select lucca and choose Authenticate.

Claude (web, desktop, mobile)

Go to Settings > Connectors > Add custom connector, paste the URL, then click Connect.

Codex

codex mcp add lucca --url "https://{account}.ilucca.net/assistant/mcp" --oauth-client-id "https://chatgpt.com/oauth/codex/client.json"

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.

VS Code, GitHub Copilot

Open the command palette, run MCP: Add Server, choose HTTP, then paste the URL.

Zed

Go to Settings > AI > MCP Servers > Add Remote Server, then paste the URL.

Goose

Run goose configure, choose Add Extension > Remote Extension (Streamable HTTP), then paste the URL.

Hermes Agent

In config.yaml:

mcp_servers:
  lucca:
    url: "https://{account}.ilucca.net/assistant/mcp"
    auth: oauth

Then run hermes mcp login lucca.

Grok

Go to 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 — 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.

Open your account

Click your avatar, then My account.

Manage connected AI

Under Connected AI, click Manage.

My Lucca account panel with the Connected AI section

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

Describe the agent

Fill in Name, Redirect URI (given by your tool, see below) 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

Copy the credentials

Copy the Client ID and Secret key into your tool.

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

Client Configuration

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

Cursor
Gemini CLI

Redirect URI: http://localhost:8787/callback

mcp.json

{
  "mcpServers": {
    "lucca": {
      "url": "https://{account}.ilucca.net/assistant/mcp",
      "auth": {
        "CLIENT_ID": "...",
        "CLIENT_SECRET": "...",
        "scopes": ["employees.readonly"]
      }
    }
  }
}

Redirect URI: http://localhost:7777/oauth/callback

settings.json

{
  "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 for every tool, the scopes it needs, and the tools on their way. See also OAuth scopes.

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

​Before You Start

​Supported Clients: Paste the URL

​Other Clients: Register the Client in Lucca

​Client Configuration

​Which Scopes to Pick

​Troubleshooting

Before You Start

Supported Clients: Paste the URL

Other Clients: Register the Client in Lucca

Client Configuration

Which Scopes to Pick

Troubleshooting