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

# Lumos Admin MCP

This guide explains how to connect an MCP-compatible AI client to the Lumos Admin MCP server, choose the toolsets you need, and run your first admin request.

# Connect to the Lumos Admin MCP Server

The Lumos Admin MCP server connects your AI client to the tools IT admins use to configure and run Lumos using the Model Context Protocol (MCP), the open standard for letting AI tools call external services. The Admin MCP Server helps you triage approvals, manage knowledge entries, audit approval policies, set up apps in the AppStore, and more in plain language, without leaving the tool you already use.

<Note>
  **Looking for help with access requests?**

  If you just want to search the AppStore and request access for yourself, use the [Lumos User MCP Server](/docs/mcp). This page is for **admins** and **privileged users** who manage Lumos.

  If you are trying to govern which MCP servers and tools your employees' agents can call, see [MCP Governance: Deployment](/docs/mcp-governance-rollout).
</Note>

## Before you begin

You need:

* A Lumos account with a privileged role. The specific tools you can run depend on your Lumos permissions, for example, a Task Center action only succeeds if your role allows it, the same as in the Lumos web app.
* An MCP-compatible client that supports remote (HTTP) MCP servers and browser-based OAuth. Supported clients include Claude Code, Claude, Codex, Gemini CLI, and OpenCode.
* Network access to the Lumos MCP endpoint.

The admin server endpoint is:

```text theme={null}
https://api.lumos.com/mcp/admin
```

You select toolsets by adding a `toolsets` query parameter to that URL, for example `https://api.lumos.com/mcp/admin?toolsets=task-center`. See [Choose your toolsets](#choose-your-toolsets) below.

## How it works

By default, you connect over OAuth in your browser. Your client opens a Lumos login page in your browser. You log in and approve a consent screen that shows what the client can do, with the permissions grouped by toolset. Lumos then gives the client a token scoped to only the permissions you approved.

You authorize each client the first time it connects. Lumos remembers your approval, so you won't log in or approve again unless your access is revoked or the client requests new permissions.

## Choose your toolsets

The admin server groups its tools into **toolsets** which are named bundles you select per connection so you load only the tools you need and save valuable context window space. To use a toolset, add a `toolsets` query parameter to the endpoint URL when you connect.

* Retrieve a reserved toolset:

  ```text theme={null}
  https://api.lumos.com/mcp/admin?toolsets=core,appstore
  ```

* Retrieve all tools:

  ```text theme={null}
  https://api.lumos.com/mcp/admin?toolsets=all
  ```

## Toolset catalog

The sections below describe each toolset's tools and show example prompts.

### `core` (default)

The default toolset when you omit the `toolsets` parameter is a read-only set that lets an agent look around your Task Center and Knowledge Hub without any write access. It contains `list_task_center_tasks`, `get_task_center_task`, `list_knowledge`, and `get_knowledge` — described under their respective toolsets below. To take actions, connect with the `task-center`, `knowledge-hub`, or `appstore` toolset.

### `task-center`

View and act on manual tasks in the Lumos Task Center — approval, provisioning, deprovisioning, and error tasks — across your own queue or the whole domain.

| Tool | Access | Purpose |
| - | - | - |
| `list_task_center_tasks` | read | List manual tasks — your own queue by default, or the whole domain for admins. |
| `get_task_center_task` | read | Fetch one task with full context: linked access request, assignees, action history, and the actions you can take. |
| `act_on_task_center_task` | write | Take an action on a task: approve, deny, override, reassign, confirm/deny provisioning, confirm deprovisioning, or resolve an error task. |

**Example prompts:**

* "What tasks are waiting on me in Lumos?"
* "Show all open provisioning tasks across the company."
* "Show me the details of task 4711 — who requested what, and who can approve it?"
* "Approve Maria's Salesforce access request."
* "Reassign the Okta provisioning task to [dana@acme.com](mailto:dana@acme.com)."
* "Retry error task 99, the integration is back up."

### `knowledge-hub`

List, inspect, create, update, and archive Knowledge Hub entries for your domain.

| Tool | Access | Purpose |
| - | - | - |
| `list_knowledge` | read | List knowledge entries with optional title and product-scope filters. |
| `get_knowledge` | read | Fetch a single knowledge entry by ID. |
| `create_knowledge` | write | Create a new knowledge entry, optionally with a file attachment. |
| `update_knowledge` | write | Patch an existing entry — only the fields you supply change. |
| `delete_knowledge` | write | Archive (soft-delete) a knowledge entry. |

**Example prompts:**

* "List our Knowledge Hub articles tagged for the AppStore."
* "Show me the full text of the 'VPN Access Policy' knowledge entry."
* "Create a knowledge article documenting our contractor offboarding steps."
* "Update the 'Onboarding checklist' entry with the new IT ticket link."
* "Archive the outdated 'Legacy VPN setup' knowledge entry."

### `appstore`

Inspect and configure the approval workflows behind your AppStore apps — who reviews access requests and under what conditions.

| Tool | Access | Purpose |
| - | - | - |
| `list_apps` | read | List AppStore apps visible to you. Includes apps not yet enrolled in the AppStore. |
| `list_app_permissions` | read | List the requestable permissions configured on an app. |
| `list_assignees` | read | List users, groups, and custom attributes that can serve as approvers. |
| `get_approval_config` | read | Retrieve the approval workflow for an app or permission. Includes stages, branches, and approvers. |
| `get_provisioning_workflow` | read | Retrieve the workflow that runs when access is granted or removed. |
| `update_app_config` | write | Update an app's app-level configuration, request-flow settings, admins, custom intake fields, metadata, and AppStore enrollment. |
| `update_approval_config` | write | Set or replace the approval template for an app or a specific permission (a full replacement). |
| `update_permission_config` | write | Update a permission's request-flow settings: visibility, requester groups, time-based access, and post-approval message. |

**Example prompts:**

* "What's the approval workflow for Figma?"
* "Which permissions are requestable on Salesforce?"
* "Who can approve access requests in our org?”
* "Show me the provisioning workflow that runs when someone is granted GitHub."
* "Change the Notion approval flow to manager first, then app admins."
* "For the Datadog Admin permission, require a security team approval instead of inheriting the app's workflow."
* "Add AWS to the AppStore with me as the admin, and make it searchable but not browsable."
* "Add a required intake question to Zoom asking why the user needs a license."
* "Set time-based access options on Miro to 30 days or 90 days, defaulting to 30."

## Connect your client

Pick your client below. Every client uses the same endpoint, `https://api.lumos.com/mcp/admin`, with the toolsets you want appended as a query parameter. The examples use `?toolsets=all`; swap in the toolsets you need (comma-separated), or omit the parameter for the default `core` set.

You can run this server and the [user server](/docs/mcp) at the same time — just give each a distinct name in your client (the examples use `lumos-admin`) so the two don't collide.

<Tabs>
  <Tab title="Claude Code">
    Add the server with HTTP transport:

    ```text theme={null}
    claude mcp add --transport http lumos-admin "https://api.lumos.com/mcp/admin?toolsets=all"
    ```

    Or add it as JSON:

    ```text theme={null}
    {
      "mcpServers": {
        "lumos-admin": {
          "type": "http",
          "url": "https://api.lumos.com/mcp/admin?toolsets=all"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude (desktop & web)">
    Add Lumos Admin as a custom connector using the remote MCP URL.

    1. Follow the [Claude custom connectors guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) .
    2. When prompted for a URL, enter the endpoint with the toolsets you want:

    ```text theme={null}
    https://api.lumos.com/mcp/admin?toolsets=all
    ```

    3. Complete the OAuth login when prompted.
  </Tab>

  <Tab title="Codex">
    Add the server to `~/.codex/config.toml` (or your Codex CLI config file):

    ```text theme={null}
    [mcp_servers.lumos-admin]
    url = "https://api.lumos.com/mcp/admin?toolsets=all"
    ```

    Then log in:

    ```text theme={null}
    codex mcp login lumos-admin
    ```

    This opens your browser to finish logging in. Codex saves your credentials until the token expires.
  </Tab>

  <Tab title="Gemini CLI">
    Run in your terminal:

    ```text theme={null}
    gemini mcp add --transport http lumos-admin "https://api.lumos.com/mcp/admin?toolsets=all"
    ```

    Or add it to \~/.gemini/settings.json:

    ```text theme={null}
    {
      "mcpServers": {
        "lumos-admin": {
          "httpUrl": "https://api.lumos.com/mcp/admin?toolsets=all"
        }
      }
    }
    ```
  </Tab>

  <Tab title="opencode">
    Add this to your `opencode.json` file:

    ```text theme={null}
    {
      "mcp": {
        "lumos-admin": {
          "type": "remote",
          "url": "https://api.lumos.com/mcp/admin?toolsets=all",
          "enabled": true
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other clients">
    Most other clients use remote (HTTP) authentication. Add the server to your client's config file with the HTTP transport and the admin endpoint, including your toolsets:

    ```text theme={null}
    {
      "mcpServers": {
        "lumos-admin": {
          "type": "http",
          "url": "https://api.lumos.com/mcp/admin?toolsets=all"
        }
      }
    }
    ```

    Then complete the OAuth login flow when prompted.
  </Tab>
</Tabs>

## Authenticate and approve access

When your client connects, Lumos opens a browser-based OAuth flow.

<Frame />

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/lumos-primary/images/docs/f94647dfd17fc111bf249450c2960514ea940244a553932a588695ea8c5734de-image.png" alt="" />
</Frame>

On the consent screen, Lumos:

* Confirms you're logged in, or asks you to log in.
* Shows which client is requesting access (for example, Claude).
* Lists the permissions it's requesting, grouped by toolset.
* Lets you approve or deny the connection.

Review the permissions and select **Authorize** to connect.

The admin server requests permissions per toolset, each with a read and a write scope:

| Toolset | Scope | What you'll see on the consent screen |
| - | - | - |
| Task Center | `lumos:admin:task-center:read` | View Task Center tasks across your domain. |
| Task Center | `lumos:admin:task-center:write` | Act on Task Center tasks (approve, deny, reassign) on your behalf. |
| Knowledge Hub | `lumos:admin:knowledge-hub:read` | View Knowledge Hub entries across your domain. |
| Knowledge Hub | `lumos:admin:knowledge-hub:write` | Create, update, and archive Knowledge Hub entries on your behalf. |
| AppStore | `lumos:admin:appstore:read` | View AppStore configurations. |
| AppStore | `lumos:admin:appstore:write` | Create and update AppStore configurations on your behalf. |

Lumos grants you only the scopes your role allows, so your token may end up with fewer scopes than the client requested. And a granted scope is a delegation ceiling, not a grant of authority: even with the scope, a tool only succeeds if your role permits the specific action — for example, administering that particular app, or being assigned to that task.

Lumos remembers your approval for the same user, client, and scopes. You'll approve again only if the client requests new scopes, your access is revoked, or the client asks for a fresh consent prompt.

## Verify your tools

After you log in, check that the Lumos admin tools appear in your client. Most clients list them in a Tools or MCP panel. Command-line clients may show them with a status or diagnostic command.

## Run your first request

Once the tools are connected, tell your agent what you need in plain language. It picks the right admin tool, asks for anything it's missing, and guides you through the action.

```text theme={null}
What approval tasks are waiting on me in Lumos?
```

## Troubleshooting

### A tool is "not in the enabled toolset(s)"

You asked your agent to use a tool that belongs to a toolset you didn't connect with. Reconnect with that toolset added to the `?toolsets=` parameter. The error names the toolset(s) that contain the tool.

### You get an "unknown toolset" error

Check the spelling and casing of the `toolsets` value. Names are lowercase and kebab-case (for example `knowledge-hub`), and the `all` keyword must be lowercase too (`all`, not `ALL`). The error lists every valid toolset name plus `all`.

### A write tool is missing, or a call fails with a missing-scope error

A write tool shows up only if your token holds the toolset's write scope, and Lumos grants that scope only when your Lumos role includes the matching permission. So a write tool is hidden (and a direct call is rejected with a missing-scope error) for one of two reasons:

* **Your role doesn't include that write permission.** Ask an org admin to grant it, then reconnect.
* **Your client connected before it requested the write scope.** Re-authorize so it requests the scope again — see [Changing your toolsets or granted scopes](#changing-your-toolsets-or-granted-scopes).

### Changing your toolsets or granted scopes

Both are fixed at connection time, so changing either means reconnecting:

* **Toolsets** live in the server's URL. Edit the `toolsets` value in your client's MCP config, then restart or reload the client.
* **Scopes** live in your saved authorization. A normal reconnect won't re-prompt you, because Lumos remembers your approval — you have to trigger a fresh authorization. For CLI clients, re-run the login (for example, `codex mcp login lumos-admin`); for other clients, remove the server from your config and add it back. Your client then re-requests scopes, and Lumos grants those your role allows.

### A tool is denied even though you approved the scope

OAuth scopes are a ceiling, not a grant. The tool also checks your Lumos role. If your role doesn't permit the action (for example, acting on another team's tasks), the tool is denied even with the scope approved. Ask an org admin to adjust your role.

### The client can't discover the server

Check that the MCP URL is correct and uses the `/mcp/admin` path (not `/mcp/user` or the Lumos web app URL). The `?toolsets=` query parameter must be part of that same URL.

### The browser login flow doesn't open

Confirm your client supports remote MCP authentication. Older clients may need an update to complete browser-based OAuth.

### You're asked to log in again

Access tokens are short-lived. If your refresh token expires or is revoked, log in again to reconnect.