MCP server

The Light AI MCP server lets AI assistants work in a contractor's Light AI account: look up leads, clients, projects and quotes, add leads, move projects through the pipeline, record quote outcomes and generate lighting mockups. It speaks the Model Context Protocol and sits directly on the public API, so each tool is one API operation with the same key, scopes, rate limits and errors.

Connect#

Every client needs the endpoint URL and the header Authorization: Bearer <your key>. Keep the key in the client's secret settings or an environment variable, never in a chat message.

Claude Code#

claude mcp add --transport http light-ai https://api.light-ai.app/mcp \
  --header "Authorization: Bearer $LIGHT_AI_API_KEY"

Claude (claude.ai and Claude Desktop)#

Customize → Connectors → Add custom connector: paste https://api.light-ai.app/mcp as the URL and, under Request headers, add Authorization with the value Bearer lai_…. Claude keeps the value private and sends it with every request. If your Claude organization does not show Request headers yet, connect Claude Desktop through the mcp-remote bridge in claude_desktop_config.json:

{
  "mcpServers": {
    "light-ai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.light-ai.app/mcp",
        "--header",
        "Authorization:${LIGHT_AI_AUTH}"
      ],
      "env": {
        "LIGHT_AI_AUTH": "Bearer lai_test_…"
      }
    }
  }
}

ChatGPT and the OpenAI API#

With the OpenAI Responses API (or the Agents SDK), add the server as a remote MCP tool and send the key as a header. Keep require_approval on for writes:

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Which leads came in this week that have no project yet?',
  tools: [{
    type: 'mcp',
    server_label: 'light_ai',
    server_url: 'https://api.light-ai.app/mcp',
    headers: { Authorization: `Bearer ${process.env.LIGHT_AI_API_KEY}` },
    require_approval: 'always',
  }],
});

In the ChatGPT app (developer mode, Settings → Apps & Connectors → Create), a connector can use this server only where ChatGPT offers an API key or bearer token option for the connector; it cannot sign in with OAuth.

Cursor#

{
  "mcpServers": {
    "light-ai": {
      "url": "https://api.light-ai.app/mcp",
      "headers": {
        "Authorization": "Bearer ${env:LIGHT_AI_API_KEY}"
      }
    }
  }
}

n8n AI agents#

• Add an MCP Client Tool node to the AI Agent's tools.
• Endpoint: https://api.light-ai.app/mcp; Server Transport: HTTP Streamable.
• Authentication: Bearer Auth, with a credential holding the API key.
• Tools to include: choose only what the agent needs (for example list_leads, get_lead, create_lead).

Check it from a terminal#

curl https://api.light-ai.app/mcp \
  -H "Authorization: Bearer $LIGHT_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" -H "Mcp-Name: whoami" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

Tools#

Each tool calls the API operation shown next to its name. Its arguments are that operation's path parameters, query parameters and body fields in one object, with the same names, types and validation as the API reference. Write tools also take idempotency_key; tools for organization data take organization for partner keys.

Write tools carry MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so clients can ask before running them. The assistant can only do what the key's scopes allow: a tool outside them answers insufficient_scope.

How tool calls behave#

• Same API, same rules. A tool call is one API request: the key, its scopes ∩ the partner grant ∩ the plan, the IP allowlist, rate limits and daily caps all apply, and it appears in the request log in Settings → Developers under the operation's route.
• Results are the API's JSON response, as structuredContent and as text. The result's _meta carries app.light-ai/request-id (quote it to support) and, for writes, the idempotency key used.
• Errors come back as tool results with isError: true and the API's error code, detail and field errors[], so the assistant can correct its arguments. A refused key ends the request with HTTP 401.
• Idempotency. Every write is sent with an Idempotency-Key: the idempotency_key argument, or a generated one reported in the result. Retrying with the same key never repeats the write (and never charges credits twice). See Idempotency.
• Partners. A partner key acts for one connected organization per call: pass its org_… id as organization (from list_partner_grants), or set a Light-AI-Organization header in the client.
• Credits. create_mockup_generation spends 5 credits per image from the contractor's balance, exactly as the Mockups API does. Test keys simulate it for free.

Security#

• Give the assistant its own key with only the scopes it needs (for example leads:read and quotes:read for a lookup assistant), so you can see its requests and revoke it without touching other integrations.
• An assistant can do everything the key allows. Keep write and credit-spending tools behind your client's approval prompt, and never paste a key into a conversation.
• Use test keys while you set up: test mode has its own data and never touches the contractor's real leads, quotes or credits (Test mode).
• Revoke or roll a key in Settings → Developers → API keys at any time; the server refuses it on the next request.
• An IP allowlist on the key also applies: cloud-hosted assistants call from their provider's addresses, not yours.
• Requests from web pages (with an Origin header) are refused, and the server has no CORS: connect from an MCP client, never from browser code.

Protocol details#

• Supported protocol versions: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26. 2026-07-28 requests carry _meta protocol metadata and the mirrored MCP-Protocol-Version, Mcp-Method and Mcp-Name headers; server/discover returns the versions, capabilities and server info. Older clients start with initialize.
• Methods: server/discover, initialize, ping, tools/list, tools/call. The server has no resources or prompts and never sends requests to the client.
• Stateless: no Mcp-Session-Id; GET and DELETE answer 405. Responses are always application/json. Batches are not accepted.
• tools/list is the same for every key (cacheable for an hour); initialize and server/discover check the key with GET /v1/me.