Connect to the Lumos User MCP Server

The Lumos user MCP server connects your AI client to the Lumos App Store using the Model Context Protocol (MCP), the open standard for letting AI tools call external services. Search the app catalog, request access, and check your request status without leaving the tool you already use.

This guide shows you how to connect a client, sign in, and run your first request.

Before you begin

You need:

A Lumos account you can sign in to through your organization's login method.
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 user server endpoint is:

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

How it works

You connect over OAuth in your browser, so you never paste an API key or token into the client. Your client opens a Lumos sign-in page in your browser. You sign in and approve a consent screen that shows what the client can do. Lumos then gives the client a token scoped to only the tools you're allowed to use.

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

Connect your client

Pick your client below. Every client uses the same endpoint: https://api.lumos.com/mcp/user.

Add the server with HTTP transport:

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

Or add it as JSON:

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

Authenticate and approve access

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

On the consent screen, Lumos:

Confirms you're signed in, or asks you to sign in.
Shows which client is requesting access (for example, Claude).
Lists the permissions it's requesting.
Lets you approve or deny the connection.

Review the permissions and select Authorize to connect.

For the user server, the requested scopes are:

Scope	What you'll see on the consent screen
`lumos:user:read`	View your access requests in the App Store.
`lumos:user:write`	Submit access requests on your behalf.

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 sign in, check that the Lumos 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.

Tool	Purpose
`search_apps`	Search the Lumos app catalog.
`search_requestable_permissions`	Search permission labels across every app you can request.
`list_requestable_permissions`	List the permissions you can request for a specific app.
`submit_access_request`	Submit a request for access to an app or its permissions.
`list_access_requests`	List your own recent access requests.

The exact tools you see depend on your Lumos permissions and your organization's feature flags.

Run your first request

Once the tools are connected, tell your agent what you need in plain language. It searches the App Store, finds matching apps and permissions, and walks you through the request.

I need access to an app that lets me view sales reports so I can prepare for the upcoming all-hands.

Troubleshooting

The client can't discover the server

Check that the MCP URL is correct and includes the /mcp/user path. Your client must connect to the MCP endpoint, not the Lumos web app 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 connected but don't see the expected tools

The tools you see depend on your Lumos role, your product access, and your organization's feature flags. If a tool you expect is missing, check these with your Lumos admin.

A write action is denied

You may have approved the lumos:user:write scope, but your Lumos role may not grant the permission the tool needs. For example, you might be able to view App Store items but not submit access requests.

You're asked to sign in again

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

Lumos Admin MCP Server

A separate Lumos admin MCP server is coming, with tools to configure and manage Lumos. Admin tools require specific scopes based on the toolset you request, and your Lumos role must allow them. We'll link the docs here when they're ready.