Build through the same governed operating layer.

One operating model, three ways in

The Lightbulb product, MCP server, and Python SDK are access surfaces over the same account-scoped platform—not three separate products with different authority models.

• Backbone is the orchestration entry point for broad objectives and cross-domain work.
• Project workflows collect facts, requirements, scope, SOP impact, approvals, and execution-ready work packets before consequential delivery.
• Domain agents perform bounded specialist work.
• Connector actions and external effects remain subject to the user’s existing scope and approval controls.

Install

The public distribution is installed directly from the Lightbulb MCP GitHub repository and requires Python 3.10 or newer.

python -m pip install --upgrade git+https://github.com/RPasquale/lightbulb-mcp.git
lightbulb
lightbulb setup

• lightbulb-mcp starts the local stdio MCP server.
• lightbulb is the helper CLI for status, guided setup, identity, approvals, document search, and one-shot platform commands.
• lightbulb setup uses device-flow login, checks the signed-in account, and merges host configuration without intentionally replacing unrelated MCP servers.

python -m pip install --upgrade git+https://github.com/RPasquale/lightbulb-mcp.git@68d215b8d6cd346770e78fa3487299de1057ddaa

Verify the installation

Check the executable, current account state, and the tool surface seen by the selected profile.

lightbulb                 # status and detected host configuration
lightbulb whoami          # authenticated identity
lightbulb tools --count-only
lightbulb tools --filter approval

• If status reports no cached login, rerun lightbulb setup and complete the browser flow.
• If the host was already open, restart it after setup so it reloads MCP configuration.
• Tool counts vary with package revision, MCP profile, and namespace filters. RBAC affects whether a listed tool can execute, not whether the local CLI lists it.

CLI reference

Use the helper CLI to inspect setup and perform small account-scoped operations without manually constructing HTTP requests.

lightbulb
lightbulb setup
lightbulb whoami
lightbulb dispatch finance --action chat --message "Summarize cash this week"
lightbulb search-documents "quarterly revenue" --top-k 5
lightbulb approvals list
lightbulb tools --filter approval

What Lightbulb MCP does

Lightbulb MCP exposes the Lightbulb platform as tools that an MCP-compatible AI host can discover and invoke under the signed-in user’s existing authority.

• Identity and company selection.
• Backbone orchestration and consulting-project starts.
• Projects, workspaces, context, document search, and operating status.
• Approvals and human-in-the-loop boundaries.
• Domain-agent and connector-backed work available to the current user.
• Code workspace and governed software-delivery loops where configured.
• Optional hosted MCP access for ChatGPT.

Tool surface and discovery

Lightbulb exposes a broad, revision-dependent tool surface. Discover the installed surface instead of treating a marketing count as an API contract.

lightbulb tools
lightbulb tools --filter backbone
lightbulb tools --filter approval
lightbulb tools --count-only

Run the stdio server

Local MCP hosts normally spawn the server as a child process over stdio.

lightbulb-mcp

python -m lightbulb.mcp_server

{
  "mcpServers": {
    "lightbulb": {
      "command": "lightbulb-mcp",
      "env": {
        "LIGHTBULB_URL": "https://agents.lightbulbpartners.com"
      }
    }
  }
}

If lightbulb-mcp is not on the host’s PATH, use python as the command and ["-m", "lightbulb.mcp_server"] as its arguments.

Claude Code setup

The guided setup path can merge a Lightbulb MCP entry into Claude Code configuration.

python -m pip install --upgrade git+https://github.com/RPasquale/lightbulb-mcp.git
lightbulb setup

1. Complete device-flow login in the browser. MFA remains in the browser flow.
2. Allow setup to merge the Lightbulb MCP entry into the chosen Claude configuration.
3. Restart Claude Code so it reloads MCP servers.
4. Ask Claude to confirm identity with whoami before company-scoped work.

Codex setup

Codex setup installs the MCP server entry and the local Lightbulb Partners plugin surface.

python -m pip install --upgrade git+https://github.com/RPasquale/lightbulb-mcp.git
lightbulb setup --target codex

• Adds a lightbulb MCP server entry to the Codex configuration.
• Installs the local Lightbulb Partners plugin bundle and skill guidance.
• Adds a personal marketplace entry so the plugin can be enabled in Codex.
• Preserves unrelated MCP servers and settings; setup writes restricted backups before changing supported configuration files.

1. Run setup and complete login.
2. Restart Codex.
3. Open Plugins and enable Lightbulb Partners if it is not already enabled.
4. For broad project or automation requests, start through the Lightbulb consulting-project workflow rather than asking a domain agent to bypass intake and approvals.

Cursor setup

Cursor can spawn the same local stdio MCP server and use the same Lightbulb account scope.

{
  "mcpServers": {
    "lightbulb": {
      "command": "lightbulb-mcp",
      "env": {
        "LIGHTBULB_URL": "https://agents.lightbulbpartners.com"
      }
    }
  }
}

1. Install the package and run lightbulb setup to create the cached device-flow token.
2. Add or merge the MCP server block without deleting existing servers.
3. Restart Cursor.
4. Confirm the signed-in identity before invoking company-scoped tools.

ChatGPT hosted MCP

ChatGPT can connect to Lightbulb through the hosted streamable HTTP MCP endpoint; it does not require the local stdio process.

https://agents.lightbulbpartners.com/mcp/lightbulb

• The health GET is public; unauthenticated MCP protocol calls receive an OAuth challenge that starts Lightbulb login and onboarding.
• The hosted surface is curated around identity, company context, status, Backbone, projects, workflows, approvals, and AutoCompany operations.
• Use the project-start path for builds, workflow automation, custom agents, SOP changes, and other work that needs intake and approval gates.
• ChatGPT is an access surface. It does not silently become the coding harness selected for a Project.

Authentication and account scope

The MCP server resolves credentials in a defined precedence order and all resulting calls remain account-scoped.

1. LIGHTBULB_JWT plus LIGHTBULB_TENANT_ID; LIGHTBULB_COMPANY_ID is optional.
2. LIGHTBULB_API_KEY plus LIGHTBULB_TENANT_ID and LIGHTBULB_USER_ID for approved loopback-only integration bootstrap.
3. A cached device-flow token under ~/.lightbulb/tokens/.
4. When running interactively with no cached token, device-flow login is attempted and the resulting token is cached.
5. LIGHTBULB_EMAIL plus LIGHTBULB_PASSWORD as a legacy fallback; MFA users should use device flow or JWT instead.

Profiles and tool-surface control

Choose the smallest useful surface so the host receives relevant tools without an unnecessarily large discovery payload.

{
  "mcpServers": {
    "lightbulb": {
      "command": "lightbulb-mcp",
      "env": {
        "LIGHTBULB_URL": "https://agents.lightbulbpartners.com",
        "LIGHTBULB_MCP_PROFILE": "backbone"
      }
    }
  }
}

The compact Backbone profile focuses on identity, company selection, Backbone orchestration, consulting-project starts, approvals, connector status, workspace context, and governed software delivery. Backbone can still coordinate permitted domain work server-side.

{
  "mcpServers": {
    "lightbulb": {
      "command": "lightbulb-mcp",
      "env": {
        "LIGHTBULB_URL": "https://agents.lightbulbpartners.com",
        "LIGHTBULB_MCP_NAMESPACES": "finance,crm,gmail,slack,jira,github,notion"
      }
    }
  }
}

Projects and the consulting workflow

Broad build and operating-change requests should begin with governed discovery instead of jumping straight to code or connector effects.

1. Capture the objective and current operating state.
2. Collect facts with provenance and identify missing information.
3. Define requirements, scope, stakeholders, systems, and acceptance criteria.
4. Identify SOP impact and preserve referenced or changed process controls.
5. Create reviewable work packets and approval gates.
6. Dispatch approved packets to the selected execution lane.
7. Verify acceptance and change plans before release actions.

In supported hosts, use start_consulting_project_workflow for project ideas, custom agents, workflow automation, SOP/process changes, modernisation, repo creation, and broad software delivery. If that exact tool is not available in an older surface, call backbone_execute and include {"workflow_type":"consulting_project_workflow"} in its inputs JSON.

Governed software delivery

When enabled, MCP hosts can enter Lightbulb’s software-delivery loop without treating the coding host as the release authority.

Managed local documents

A configured local runtime separates user-visible working files from hidden service-managed storage.

These folders exist only when the managed local runtime has been installed and configured. Installing the public MCP package alone does not create or index a company document estate.

Runtime behaviour

The host sees MCP tools; the Lightbulb platform remains authoritative for what those tools may do.

SDK status and stability

The Python client ships in the `lightbulb-mcp` package, but the public repository describes it as preview / unstable.

• Python 3.10 or newer is declared by the public package metadata.
• The package includes LightbulbClient, AsyncLightbulbClient, authentication helpers, typed error classes, and selected integration helpers.
• The wheel carries a py.typed marker for type-checker consumers.
• MCP and the helper CLI are the supported public developer surface today; the SDK should be treated as beta.

Synchronous client

Use device-flow authentication for an interactive human session, then create an account-scoped client.

from lightbulb import LightbulbClient, device_login

BASE = "https://agents.lightbulbpartners.com"

# Browser-based login keeps MFA in the user flow.
auth, _expires = device_login(BASE, client_id="my-app")
client = LightbulbClient(BASE, auth=auth)

print(client.whoami())
result = client.dispatch(
    "finance",
    action="chat",
    message="Summarize cash this week",
)
print(result.reply)

Client capability reference

The synchronous preview client is the broadest Python surface; method availability is revision-dependent and still subject to platform permissions.

SDK authentication

Device flow is the preferred interactive path. JWT and approved local bootstrap credentials support non-interactive environments.

from getpass import getpass

from lightbulb import (
    LightbulbClient,
    TwoFactorRequired,
    complete_2fa_login,
    login,
)

BASE = "https://agents.lightbulbpartners.com"
email = input("Email: ").strip()
password = getpass("Password: ")

try:
    auth = login(BASE, email, password)
except TwoFactorRequired as exc:
    code = getpass("Authenticator code: ").strip()
    auth = complete_2fa_login(exc.base_url, exc.email, code)

client = LightbulbClient(BASE, auth=auth)

Asynchronous client

Use the async client inside event-loop applications, while treating method coverage as a beta surface that may differ from the sync client.

import asyncio
import os

from lightbulb import AsyncLightbulbClient, JwtAuth

BASE = "https://agents.lightbulbpartners.com"

async def main():
    auth = JwtAuth(
        token=os.environ["LIGHTBULB_JWT"],
        tenant_id=os.environ["LIGHTBULB_TENANT_ID"],
        company_id=os.getenv("LIGHTBULB_COMPANY_ID"),
    )
    async with AsyncLightbulbClient(BASE, auth=auth) as client:
        me = await client.whoami()
        print(me)

asyncio.run(main())

The public repository describes async coverage as curated for important paths. Check the installed package before assuming every synchronous method has an identical native-async implementation.

Refresh expired authentication

Provide a refresh callback and retry only after the client has installed refreshed credentials.

from lightbulb import AuthenticationError, LightbulbClient
from lightbulb.auth import device_login

BASE = "https://agents.lightbulbpartners.com"
initial_auth, _expires = device_login(BASE, client_id="my-worker")

def refresh():
    auth, _expires = device_login(BASE, client_id="my-worker")
    return auth

client = LightbulbClient(
    BASE,
    auth=initial_auth,
    auth_refresh=refresh,
)

try:
    client.dispatch("crm", action="chat", message="hello")
except AuthenticationError:
    if client.refresh_auth():
        client.dispatch("crm", action="chat", message="hello")

Use await client.refresh_auth() with AsyncLightbulbClient.

Errors and retry policy

The SDK maps HTTP failures to Lightbulb-specific exception types rather than exposing raw HTTP client exceptions at every call site.

Typed integration helpers

The public package includes selected higher-level helpers in addition to the general platform client.

• Stripe: StripeOrchestratorClient and StripeWorkflow.
• Xero: XeroAgentClient and XeroPlaybook.
• Thin connector helpers for Slack, Jira, BambooHR, Greenhouse, and Monday where present in the installed revision.

Typed operating model: current direction

Newer source candidates are developing a typed company-building model, but those contracts should not be presented as a stable public SDK until their release gates close.

• Business Process Primitives: typed blocks for real company tasks.
• Workflow definitions: ordered, reviewable compositions with hidden setup, states, retries, and approval policy.
• Connector execution: one governed seam for preview, approval, idempotency, and provider effects.
• Projects and Company Blueprints: scoped declarations of workflows, connectors, policies, departments, metrics, and execution lanes.
• Runtime outcomes: sanitized operational evidence for debugging and improvement without storing raw business payloads in telemetry.

Governance model

Lightbulb is designed around explicit authority boundaries rather than assuming an AI host may act simply because it can formulate a request.

• A preview is not a live connector effect.
• A draft is not published work.
• Implementation approval is not automatically deployment approval.
• A visible tool is not proof of permission.
• A successful local simulation is not a customer-outcome or production-certification claim.

Security guidance

Most integration failures are recoverable; credential exposure and authority confusion are not. Design the host configuration accordingly.

• Use HTTPS for every non-loopback Lightbulb URL.
• Prefer device-flow login and the protected token cache for human workstations.
• Keep secrets out of committed MCP files, notebooks, shell history, screenshots, and prompt context.
• Scope generated MCP namespaces to the work the host actually needs.
• Confirm identity and company context before consequential work.
• Treat approval references, idempotency keys, and server-issued resource references as opaque values.
• Sanitize support reports; do not paste complete HTTP bodies, tokens, or customer payloads.
• Use a short-lived, least-privilege user-scoped JWT for approved remote automation; keep API-key bootstrap loopback-only.

The public SDK documents HTTPS enforcement for non-local hosts, validation of risky path inputs and browser URLs, atomic token-cache writes, restrictive permissions, and safer configuration merging. Your host and deployment environment still need their own secret-management and endpoint-hardening controls.

Troubleshooting

Start with identity, process visibility, and the installed package before debugging a specific tool.

python --version
python -m pip show lightbulb-mcp
lightbulb
lightbulb whoami
lightbulb tools --count-only
lightbulb tools --filter approval

Version and release status

This documentation separates what the public repository supports today from newer source-candidate concepts that remain unreleased or gated.

This page was reviewed against the public RPasquale/lightbulb-mcp main branch at commit 68d215b8 on 30 August 2026, with unreleased concepts cross-checked against local Lightbulb source evidence. Recheck the source link before relying on exact flags, exports, or tool families in a long-lived integration.

• Public source repository
• Lightbulb product
• Partner documentation

Get help

Include the minimum safe diagnostic context so the team can reproduce the issue without receiving credentials or customer data.

• Operating system and Python version.
• Installed Git revision or package version.
• Host: Claude Code, Codex, Cursor, ChatGPT, or another reviewed MCP client.
• MCP profile and namespace filter, with all secrets removed.
• The tool name or CLI command and the sanitized error class/message.
• Whether identity and company selection succeeded.
• Whether the operation was read-only, preview, approval-gated, or intended as a live effect.

• Contact Lightbulb Partners
• Open the public source