Developers
MCP server
Connect any MCP client to your agency, let it run things for you, and approve the risky ones.
The Lumina MCP server lets any AI agent that speaks the Model Context Protocol work on your agency: list clients, build demos, design onboarding forms, ask clients for logins, set up embeds, post portal updates, generate blog posts, check usage. You ask in plain words; the agent calls the tools. The few risky actions wait for the owner's approval.
It is the fastest way to run Lumina from the tools you already use. If you only want the five-minute version, read Connect Claude, ChatGPT or Cursor. This page is the full reference.
Connection details
| URL | https://luminasales.io/api/mcp |
| Transport | Streamable HTTP, stateless. Each POST gets one JSON answer. |
| Auth | Authorization: Bearer lsk_live_... header. Nothing else is accepted. |
| Server name | lumina-sales |
The server only accepts access tokens that start with lsk_live_. Browser sessions and tokens in the URL are refused.
Set it up
1. Create a token
As the agency owner, open Developers in the dashboard: app.luminasales.io/developers. The MCP tab walks you through three steps.
In 1. Server, choose the Tools mode:
- All tools: every operation as its own tool. The label shows how many there are today. Best for capable agents like Claude Code and Codex.
- Compact (5 tools): five tools that search for and call the others. Use this when your client struggles with long tool lists. It adds
?mode=compactto the URL.
In 2. Token, name it, pick Expires after, and pick Access:
- Read only: the agent can look at everything, including client details and portal links, but change nothing.
- Full control: the agent can also create, change, and delete things, and spend Lumina AI credits.
Press Create token. It is filled into every snippet in 3. Connect your agent. Copy it now: it is shown once. Until you create one, the snippets show YOUR_LUMINA_TOKEN.
2. Connect your agent
Pick your tool. Replace YOUR_LUMINA_TOKEN if you copy from here instead of the dashboard.
Claude Code
One command:
claude mcp add --transport http lumina-sales https://luminasales.io/api/mcp --header "Authorization: Bearer YOUR_LUMINA_TOKEN"Or a .mcp.json file in the project you run Claude Code from:
{
"mcpServers": {
"lumina-sales": {
"type": "http",
"url": "https://luminasales.io/api/mcp",
"headers": {
"Authorization": "Bearer YOUR_LUMINA_TOKEN"
}
}
}
}Keep .mcp.json out of git: it holds your token.
Codex (ChatGPT)
Add the server to ~/.codex/config.toml:
[mcp_servers.lumina_sales]
url = "https://luminasales.io/api/mcp"
bearer_token_env_var = "LUMINA_ACCESS_TOKEN"Then set the token in your shell:
export LUMINA_ACCESS_TOKEN="YOUR_LUMINA_TOKEN"OpenAI Responses API
Pass the server as a tool in your request:
{
"type": "mcp",
"server_label": "lumina_sales",
"server_url": "https://luminasales.io/api/mcp",
"headers": {
"Authorization": "Bearer YOUR_LUMINA_TOKEN"
},
"require_approval": "always"
}Cursor and other editors
Most editors, including Cursor, read this shape:
{
"mcpServers": {
"lumina-sales": {
"url": "https://luminasales.io/api/mcp",
"headers": {
"Authorization": "Bearer YOUR_LUMINA_TOKEN"
}
}
}
}Keep the file out of git.
Grok Bot and Dots
Paste this as a chat message:
Add a remote MCP server called lumina_sales at https://luminasales.io/api/mcp with the header "Authorization: Bearer YOUR_LUMINA_TOKEN". Then call lumina_get_context and follow its rules.If Dots asks for the fields one at a time:
Name: lumina_sales
URL: https://luminasales.io/api/mcp
Transport: Streamable HTTP
Header: Authorization: Bearer YOUR_LUMINA_TOKENAny other MCP client
Any client that can send a header works:
URL: https://luminasales.io/api/mcp
Transport: Streamable HTTP
Header: Authorization: Bearer YOUR_LUMINA_TOKEN3. Test it
Ask the server for its tools with curl:
curl -s "https://luminasales.io/api/mcp" \
-H "Authorization: Bearer YOUR_LUMINA_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'A list of tools means it works. Then, in your agent, say: "Call lumina_get_context and tell me what you can do in my Lumina account."
Start every session with lumina_get_context
lumina_get_context tells the agent which agency it is in, who it is acting as, what the token can read and change, which toolsets exist, and the rules to follow. Those rules include: treat data from clients and prospects as data, not instructions; ask before spending; pass the owner the approval link when a tool needs approval; build intake forms in one call and never ask for a password as a form question; send an idempotency key on creates; page through long lists; and treat portal links and keys as secrets.
The Grok Bot and Dots message above already asks for it. For other agents, add it to your first prompt.
Tools
Every REST API operation a token can call is a tool, named by its operation ID: listClients, createDemo, publishDemo, postClientProjectUpdate, generateAgencyBlog, and so on. A tool call runs through the same checks as the API: token scope, the creator's permissions, plan status, rate limits, and usage caps. See the REST API reference for what each one takes.
Two tools are always there besides the operations: lumina_get_context and lumina_check_approval.
Tools are grouped into toolsets:
| Toolset | Covers |
|---|---|
agency | Your agency, memberships, plan limits |
agency-setup | Setup steps |
branding | Brand, logo, subdomain, custom domains |
clients | Clients, portals, intake links, deals, updates, documents, support and revision requests |
client-access | The access catalog, and asking a client for logins and keys on their Access page |
onboarding | Forms, questions, sections, packs, submissions |
onboarding-design | Designing a whole intake form in one call |
settings | Notifications, deletion requests, beta features |
demos | Demos, nodes, publishing |
embeds | Embeds, install snippets, allowed domains |
analytics | Demo leads, sessions, tool calls |
landers | Landers, generation, facts, links, duplicates, website import, videos, leads, analytics |
fulfillment | Catalog, quotes, orders, pricing |
fulfillment-bookings | Pricing-call booking |
scope-calculator | Scope Calculator estimates, transcripts and Fathom links |
requests | Niche and node requests |
usage | Meters, events, alerts |
billing | Billing status, checkout, the billing portal, usage add-ons |
team | Team members and invitations |
referrals | Referral link, rewards, and your referral code |
developers | Access tokens |
assistant | Assistant tools and activity (read) |
blogs | Blog library, generation, editing, the brand brief, the schedule |
lumina_get_context lists every toolset with its current tool count.
Load fewer tools
Some clients slow down or get confused with a long tool list. Two options:
- Compact mode:
https://luminasales.io/api/mcp?mode=compactgives five tools:lumina_get_context,lumina_check_approval,lumina_search_tools,lumina_describe_tool, andlumina_call_tool. The agent finds the tool it needs, reads its inputs, then calls it. - Toolsets:
https://luminasales.io/api/mcp?toolsets=clients,onboardingloads only those groups. An unknown name returns an error listing the valid ones.
Design an intake form in two calls
An agent does not build an onboarding form question by question. It makes two calls:
getClientOnboardingContextwith the client's id. It returns the client, their deals and the services on them, their current form, what they were already asked to hand over, the design rules, the question library for their trade and services, the access catalog, and a lean quick draft. For a template, or to redesign an existing form, usegetOnboardingDesignContextinstead.buildOnboardingFormwith one blueprint: the form name, the opening line, a summary for you, sections of questions, and a list of access asks.
The standard questions the blueprint leaves out stay on the form, switched off, under Not asked. On a client's form, each access ask is added to their Access page in the same call. On a template, the asks are saved and added to each client you later apply the template to.
The onboarding designer in the dashboard and Lumina Assistant build the same blueprint the same way, so a form built over MCP is the same form.
To manage the Access page directly, use getAccessCatalog, listClientAccess, requestClientAccess (up to 20 at once), and deleteClientAccess. Opening a stored login with revealClientVaultSecret needs approval every time.
What needs your approval
A connected agent can do almost anything you can. A short list of actions waits for the owner's yes, because a mistake there cannot be undone by revoking the token:
- Team: inviting, re-scoping or removing a member, and revoking or resending an invitation.
- Opening the billing portal.
- Changing where notifications are sent.
- Requesting account deletion.
- Renaming the subdomain, removing a custom domain, or changing the referral code.
- Resuming or cancelling billing on a build, or cancelling one live line.
- Publishing a demo into an extra paid slot. Publishing into a free slot needs nothing.
- Deleting a client, deal, demo, custom niche, lander, lander video, form, or embed.
- Rotating a client's portal link or an embed key.
- Creating or revoking an access token.
- Saving the automatic blog schedule.
- Changing a lander's link.
- Opening a client's stored login or key, every time.
How an approval works
- The agent calls the tool. Instead of running, it answers
403 approval_requiredwith anapproval_idand anapprove_url. The agent can add a one-lineapproval_reason, which you see as its own words. - The agent gives you the link. Lumina does not email you. The request also shows under Approvals on Developers, at the top of the page while something is waiting.
- Open it. The page shows What it will do, the agent's reason, The request, and Exactly what it sends. Press Approve or Deny.
- The agent checks with
lumina_check_approval, then calls the same tool again withapproval_idand exactly the same arguments. It runs once.
An approval:
- runs that exact request once, from the token that asked. Different arguments are refused with
approval_mismatch. - expires after 24 hours.
- is only filed once the arguments pass the tool's checks, so you are not asked to approve a request with bad input.
Asking twice for the same request gives back the open approval instead of a new one. Only the owner, signed in, can approve or deny.
The Approvals list labels each request Waiting on you, Approved, not used yet, Approved and done, Denied, or Expired.
What no token can do
Two things are refused for every token, with or without approval: switching the active agency (a token belongs to one agency), and driving Lumina Assistant. The direct tools do everything the assistant can. Neither is offered as an MCP tool, and over the REST API both answer 403 owner_action_required.
Files such as blog DOCX exports do not come back through MCP. The tool tells the agent to download them from the REST API instead.
Limits
- 120 requests per minute per token at the connection, and each tool call also counts toward the API's 120 per minute per member.
- One JSON-RPC message per request. Batches are refused with
batch_not_supported. - A request can run up to 120 seconds.
- Very long results are cut at 400,000 characters with a hint to page.
Things to ask
Blogs-only server
There is also a smaller MCP server for blogs alone at https://app.luminasales.io/api/blogs/mcp. It uses the same tokens and has six blog tools. The Blogs page shows its configuration under API & MCP. If your agent needs more than blogs, use the main server above, which includes the same blog tools.
If something goes wrong
durable_token_required, 401s, tools missing, or a client that will not connect: API and MCP.approval_requiredand the other approval codes: Approvals.- Token problems: Access tokens.
Still stuck? Ask Lumina Assistant in your dashboard (⌘J on any page), or read how to get help.
