MCP Getting Started

Use this guide if you are evaluating Lumos MCP for your organization, or an IT app administrator helping employees use approved agents for access workflows. Check out our customer-facing Help Center Article here.

Before you begin

You need the following:

• A Lumos tenant with MCP enabled for your organization.
• A Lumos user account that can sign in through your organization's configured login method.
• Product access to the Lumos workflow you want to use, such as App Store access requests.
• A supported MCP client or host, such as Claude, Claude Code, Codex, Gemini, Cursor, Glean, or another client that supports remote MCP servers and browser-based OAuth.
• Network access to the Lumos MCP endpoint.

For the initial App Store server, the production endpoint is:

https://api.lumos.com/mcp/appstore

How connection works

When you add a Lumos MCP server to an AI client, the client discovers the protected resource metadata from Lumos, finds the Lumos authorization server, registers or uses an approved OAuth client profile, and opens a browser-based login flow.

The user then signs in to Lumos and reviews a consent screen. After approval, the MCP client receives a token scoped to the Lumos MCP resource and can call the tools the user is authorized to use.

Steps to connect:

1. Add the Lumos MCP endpoint to the AI client.
2. Start the MCP connection.
3. Sign in to Lumos in the browser.
4. Review and approve the requested permissions.
5. Verify that Lumos tools are listed in the client.
6. Ask the agent to perform a Lumos workflow.

Step 1: Choose the Lumos MCP server

Choose the MCP server that matches the workflow.

Step 2: Add Lumos MCP to your client

Exact setup steps vary by MCP client. Most clients need a remote MCP URL.

Use the Lumos MCP endpoint as the server URL:

https://api.lumos.com/mcp/appstore

Example: Claude Code

Add the Lumos App Store MCP server with HTTP transport:

claude mcp add --transport http lumos-appstore https://api.lumos.com/mcp/appstore

Then log in if your client requires a separate login command or prompts you to authenticate when the server starts.

Example: Cursor, VS Code, Gemini CLI, or other clients

Add a remote HTTP MCP server using the client's MCP settings. Use the Lumos endpoint for the selected server.

Example JSON-style configuration:

{
  "mcpServers": {
    "lumos-appstore": {
      "type": "http",
      "url": "https://api.lumos.com/mcp/appstore"
    }
  }
}

Example: Glean or another enterprise MCP host

Register the Lumos MCP server as a remote MCP server using the host's administrative configuration. Lumos supports OAuth-based discovery and Dynamic Client Registration for host integrations that require it. The exact redirect URI and client policy are validated by Lumos host profiles.

Step 3: Authenticate with Lumos

When the client starts the connection, Lumos opens a browser-based OAuth flow.

During authentication:

• Lumos verifies the user's session or prompts the user to sign in.
• Lumos displays the client or agent name when available.
• Lumos displays the redirect hostname used by the client.
• Lumos displays the requested permissions in human-readable language.
• The user can approve or deny the connection.

For the App Store server, common consent descriptions include:

Consent is remembered for the same user, client, Lumos MCP resource, and scopes. Re-consent is required if the client asks for additional scopes, the grant is revoked, or the client explicitly requests a new consent prompt.

Step 4: Verify available tools

After authentication, confirm that the client lists Lumos tools. In many clients, tools appear in a Tools or MCP settings panel. In command-line clients, the tool list may be shown through a diagnostic or server status command.

For the App Store server, expected tools include:

The exact tools shown depend on the user's Lumos permissions, the requested scopes, the organization's feature flags, and the connected MCP server.

Step 5: Try your first prompt and refine the agent

Use a prompt that asks the agent to inspect before writing.

Example admin prompt:

List which apps are visible on in the app store. 

Example access request prompt:

I need access to an App that allows me to view sales reports so that I can generate reports for upcoming all hands meetings.

Refine the agent using the Knowledge Hub

The Knowledge Hub is a centralized repository in Lumos where you can store organizational context, documentation, and information about your applications and permissions. It serves as the "brain" that powers Lumos's AI agents, including the access request agent used in the app store and MCP.

What the Knowledge Hub Does

The Knowledge Hub allows you to:

• Add custom context about your applications and what they're used for
• Define naming conventions for permissions (especially useful for custom apps)
• Upload documentation or create prompts that explain your organization's specific terminology
• Scope context globally or to specific features (like the AppStore) or individual applications
• Provide guidance on common access patterns and appropriate use cases

Why It's Useful for the App Store

For the app store specifically, the Knowledge Hub is valuable because:

1. Better AI Recommendations: When users interact with the conversational access request agent, it uses Knowledge Hub content to understand what they need and suggest the right apps and permissions. For standard apps, Lumos auto-generates context, but for custom apps, you'll need to provide this information.
2. Organizational Context: You can teach the AI about your company's specific terminology, team structures, and access patterns. For example, if you have naming conventions like "ECH-*" groups or specific permission structures, you can document these so the AI understands them.
3. Reduces Wrong Requests: By providing clear context about what apps and permissions are for, the Knowledge Hub helps prevent users from requesting the wrong access, reducing noise for approvers.
4. Works Across Channels: The same Knowledge Hub content powers the access request experience whether users are requesting through the web app store, Slack, or other integrations like Claude/MCP.
5. Audit Trail: The Knowledge Hub provides transparency for auditors by documenting why certain access decisions are made and what organizational policies guide them.

Lumos automatically generates Knowledge Hub entries for standard applications, but you'll want to add custom entries for your organization-specific apps, naming conventions, and policies to get the most value from the AI-powered app store experience.

Troubleshooting

The client cannot discover the server

Confirm that the MCP URL is correct and includes the server path, such as /mcp/appstore. The client should connect to the MCP resource server, not the Lumos web application URL.

The browser login flow does not open

Confirm that your MCP client supports remote MCP authentication. Some local clients or older versions may require an update before they can complete browser-based OAuth.

The user can connect but does not see expected tools

Check the user's Lumos role, product access, requested scopes, and the organization's MCP feature flags. Lumos filters or denies tools when the user's token does not include the required effective permissions.

A write action is denied

The user may have approved a broad OAuth scope, but the user's Lumos role may not grant the internal permission required by the tool. For example, a user may be allowed to view App Store items but not create access requests.

The same request already exists

Lumos deduplicates common write actions. If a matching pending request already exists for the same target user, app, and permission set, the MCP tool can return the existing request instead of creating a new one.

The connection asks the user to sign in again

Access tokens are short-lived. If the refresh token expires, is revoked, or triggers reuse protection, the user must complete the OAuth flow again.