Use LightHouse in Claude

View as Markdown

Claude connects to LightHouse™ as a remote MCP server and calls LightHouse’s tools for agents and their runs, usage and cost, and knowledge retrieval from the organisation’s own sources. Each call runs as the person who signed in, under that person’s LightHouse role and the scopes they approved.

Model use. Claude calls LightHouse’s tools over MCP. The agents and the retrieval behind those tools run on the organisation’s deployment, on the model providers connected to LightHouse. Claude’s model answers in the Claude conversation only. A Claude subscription does not run Atlantic agents and is not a model backend for them.

Claude product	Connection	Credential
Claude on the web, the desktop app and mobile	A custom connector	OAuth, at the hosted endpoint
Claude Code	`claude mcp add`	OAuth at the hosted endpoint, or a machine key at the portal’s endpoint
An application on the Claude API	The MCP connector	An OAuth token, at the hosted endpoint
An application on the Claude Agent SDK	`mcp_servers`	A machine key at the portal’s endpoint, or an OAuth token

Requirements

Requirement	Detail
Hosted endpoint enabled	Required for every route that signs in with OAuth. The address answers only where Atlantic has enabled the hosted endpoint (Availability).
Tenant ID	The first label of the portal’s address, beginning `t-`.
Machine key (machine-key routes only)	A `viewer` key from Settings → Keys and the tenant’s Access service token (Authentication).

The hosted endpoint, used throughout this page:

https://mcp.atlanticagenticlabs.com/t/<tenant id>/mcp

Claude on the web and in the desktop app

The web app, the desktop app and the mobile apps share one set of connectors per Claude account. A connector added once is available in each.

On a Team or Enterprise plan

An Owner adds LightHouse for the organisation. On an Enterprise plan, a member whose custom role includes managing the organisation’s libraries can also add it. Members cannot add a custom connector themselves.

Go to Organization settings → Connectors.
Select Add, then Custom. If Claude asks for the connector type, choose Web.
Enter the name LightHouse and the hosted endpoint’s address, with the tenant ID in place of <tenant id>.
Under authentication, keep the options Claude marks Detected. For the OAuth client, choose Register automatically. LightHouse registers Claude by dynamic client registration and issues no client secret. Leave the request headers empty.
Select Add.

Result: LightHouse is listed under the organisation’s connectors with the Custom label.

Each member then connects with their own LightHouse identity: Customize → Connectors, select LightHouse (labelled Custom), then Connect.

On a Free, Pro, Max or Ultra plan

Go to Customize → Connectors.
Select Add, then Add custom connector.
Enter the name LightHouse and the hosted endpoint’s address, then select Continue.
Keep the options Claude marks Detected, choose Register automatically for the OAuth client, and select Add.
Select Connect and sign in (Sign in).

The Free plan allows one custom connector.

Select Connect on the LightHouse connector.

Result: the browser opens the portal’s approval page, https://<tenant id>.atlanticagenticlabs.com/oauth/authorize. If the portal requires it, sign in through the identity provider.
Review the request and select Approve.

Result: the browser returns to Claude and the connector shows as connected.

Claude stores the token on Anthropic’s servers and renews it while the connector is in use. Calls to LightHouse are made from Anthropic’s servers. The person’s browser and computer do not call LightHouse.

Claude: a custom connector
MCP endpoint: LightHouse, hosted
Tenant portal: at the tenant's address
Person: signed in through the identity provider

Discovery and registration

Claude to MCP endpoint: First request, no token
MCP endpoint to Claude: Refused, naming where to sign in. the endpoint's protected-resource document names the portal
Claude to Tenant portal: Register. dynamic registration: an identifier, no secret

Approval

Claude to Tenant portal: Open the approval page. with a PKCE challenge (S256)
Tenant portal to Person: Who is asking, where the answer goes, each scope. after sign-in with a second factor
Person to Tenant portal: Approve. recorded in the tenant's audit log
Tenant portal to Claude: A single-use code. bound to the client and its redirect
Claude to Tenant portal: Code and verifier for a token. one tenant, one person, the approved scopes

Use

Claude to MCP endpoint: Tool call, with the token. read-only tools
MCP endpoint: Checked, then audited. scope and role checked before the tool runs; each knowledge read audited to the person

Claude discovers the tenant's portal from the endpoint, registers by dynamic client registration without a secret, and opens the portal's approval page for the person. Each tool call then runs as that person, under their role and approved scopes, and is audited.

Approval page

The approval page shows:

The client. Claude’s answer is sent to https://claude.ai/api/mcp/auth_callback. LightHouse recognises the client by that address, names it Claude regardless of the name it registered under, and states that the sign-in is kept on Anthropic’s servers. A client that calls itself Claude but uses any other address is shown with the line stating that LightHouse cannot confirm which application it is.
The return address for the answer.
The scopes, one sentence per scope. Claude requests the scopes the endpoint names: telemetry:read, agents:read and knowledge:read. knowledge:read returns records only to a person who holds the content_viewer role.

If the person declines, Claude receives access_denied and the connector remains disconnected.

Tools

In a conversation, select +, then Connectors, and confirm that LightHouse is on.
Enter a question, for example “Which of our agents failed most often this week?” or “Search our knowledge bases for the current release procedure.”

Result: Claude asks for permission before it runs a LightHouse tool, unless that tool has been allowed.

To block a tool, open Customize → Connectors, select LightHouse and set that tool’s permission to Blocked. The tools available to a delegated token read data only. No tool approves, pays, deploys or changes a limit (Read only, deliberately).

Claude Code

With OAuth

Add the hosted endpoint:

claude mcp add --transport http lighthouse "https://mcp.atlanticagenticlabs.com/t/<tenant id>/mcp"

Open /mcp in Claude Code, select lighthouse and choose Authenticate. claude mcp login lighthouse starts the same sign-in from the command line.

Result: the browser opens the portal’s approval page.
Approve the request.

Result: Claude Code stores the token and lighthouse shows as connected.

Claude Code receives the answer on the local computer. The approval page therefore states that the answer goes to an application on this computer and shows the name the client registered under. Approve the request only if the person approving it started the sign-in from Claude Code immediately beforehand.

--scope sets where the server is recorded:

`--scope`	Recorded for
`local` (default)	The current user, in this project
`user`	The current user, in every project
`project`	Everyone working on the project, in its `.mcp.json` file

With OAuth, the configuration holds no key, token or secret, and a project’s .mcp.json can be committed.

With a machine key

Connect to the portal’s endpoint with a viewer key and the tenant’s Access service token, set as AAL_TENANT, AAL_KEY, CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET (With a machine key):

claude mcp add --transport http lighthouse "https://$AAL_TENANT.atlanticagenticlabs.com/mcp" \
  --header "Authorization: Bearer $AAL_KEY" \
  --header "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  --header "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"

Result: claude mcp list shows lighthouse as connected.

Do not add a server with a key at --scope project. The key would be written to .mcp.json.

In Claude Code, LightHouse’s tools are named mcp__lighthouse__<tool>, for example mcp__lighthouse__agents.

For developers

The Claude API MCP connector

With the MCP connector, Anthropic’s servers connect to the MCP server, list its tools and call them during a Messages API request. The application does not need an MCP client.

Anthropic’s servers send the MCP server one credential, an OAuth token passed as authorization_token, and no other header. Use the hosted endpoint with a delegated token (lhat-) for the person the application acts for. The portal’s endpoint cannot be used with the MCP connector, because it also requires the tenant’s Access service token in headers.

The application obtains the token in the same way as any MCP client: register a client, send the person to their portal’s approval page with a PKCE challenge, and redeem the code (Signing in with OAuth). Refresh the token when it expires and send it with every request.

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": "Which of our agents failed most often this week?"}],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://mcp.atlanticagenticlabs.com/t/<tenant id>/mcp",
        "name": "lighthouse",
        "authorization_token": "'"$LIGHTHOUSE_TOKEN"'"
      }
    ],
    "tools": [
      { "type": "mcp_toolset", "mcp_server_name": "lighthouse" }
    ]
  }'

In Python:

import os

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "Which of our agents failed most often this week?"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://mcp.atlanticagenticlabs.com/t/<tenant id>/mcp",
            "name": "lighthouse",
            "authorization_token": os.environ["LIGHTHOUSE_TOKEN"],
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "lighthouse"}],
    betas=["mcp-client-2025-11-20"],
)

Tool selection. In the toolset, "default_config": {"enabled": false} with "configs": {"agents": {"enabled": true}, "runs": {"enabled": true}} offers Claude those two tools only.
Response. Each call is returned as an mcp_tool_use block and its answer as an mcp_tool_result block. A LightHouse refusal, such as scope_required, is returned as a result with is_error set.
Data handling. Anthropic’s documentation states that MCP connector data is not covered by zero data retention arrangements. Consider this before sending knowledge reads through the connector.

The Claude Agent SDK

An agent built on the Claude Agent SDK runs on the organisation’s own machines or servers and connects to MCP servers from there. It can use either endpoint. For an unattended agent, use the portal’s endpoint with a machine key:

import asyncio
import os

from claude_agent_sdk import ClaudeAgentOptions, query

options = ClaudeAgentOptions(
    mcp_servers={
        "lighthouse": {
            "type": "http",
            "url": f"https://{os.environ['AAL_TENANT']}.atlanticagenticlabs.com/mcp",
            "headers": {
                "Authorization": f"Bearer {os.environ['AAL_KEY']}",
                "CF-Access-Client-Id": os.environ["CF_ACCESS_CLIENT_ID"],
                "CF-Access-Client-Secret": os.environ["CF_ACCESS_CLIENT_SECRET"],
            },
        }
    },
    allowed_tools=["mcp__lighthouse__*"],
)

async def main() -> None:
    async for message in query(prompt="Summarise this week's failed runs.", options=options):
        print(message)

asyncio.run(main())

In TypeScript, with @anthropic-ai/claude-agent-sdk:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Summarise this week's failed runs.",
  options: {
    mcpServers: {
      lighthouse: {
        type: "http",
        url: `https://${process.env.AAL_TENANT}.atlanticagenticlabs.com/mcp`,
        headers: {
          Authorization: `Bearer ${process.env.AAL_KEY}`,
          "CF-Access-Client-Id": process.env.CF_ACCESS_CLIENT_ID!,
          "CF-Access-Client-Secret": process.env.CF_ACCESS_CLIENT_SECRET!,
        },
      },
    },
    allowedTools: ["mcp__lighthouse__*"],
  },
})) {
  console.log(message);
}

To act for a person, connect to the hosted endpoint with "headers": {"Authorization": "Bearer <their lhat- token>"}. The SDK does not open a browser or run a sign-in. The application obtains the token as described for the MCP connector.

allowed_tools lets the agent call the listed LightHouse tools without asking. List individual tools, such as mcp__lighthouse__runs, to restrict it.

Audit

LightHouse checks and records requests from Claude in the same way as requests from any other MCP client:

Event	Record
Approval	Each person’s approval or decline is written to the tenant’s audit log, with the client’s name and the scopes approved.
Knowledge read	Each `knowledge` tool call is audited as a content read by the person who signed in, or by the key that made it.
Refusal	A sign-in refused because the person’s access has been withdrawn is audited.
Credential use	Settings → Keys shows each key’s last use. Settings → Keys → Signed-in tools shows each delegated token, its scopes and its last use.

Claude keeps its conversation history under the settings of the Claude account or organisation. LightHouse does not receive it.

Revoke access

Credential	Where to revoke
A person’s delegated token	The person revokes it in Settings → Keys → Signed-in tools. Claude then asks the person to connect again.
The organisation’s connector	An Owner removes it in Organization settings → Connectors in Claude.
A machine key	Settings → Keys

When a person’s access is withdrawn in LightHouse, their token stops working immediately, including the copy Claude holds.

Troubleshooting

Symptom	Cause
Claude reports that it could not reach the MCP server	The hosted endpoint is not enabled for the platform (Availability), or the tenant ID in the address is wrong.
Claude reports that authorisation with the MCP server failed	The sign-in was declined or expired, or the address names another tenant. Select Connect again.
A member cannot add the connector	On a Team or Enterprise plan, only an Owner, or an Enterprise member with a role that manages the organisation’s libraries, can add custom connectors.
The Messages API returns an error for the MCP server	The `authorization_token` is missing, expired or revoked, or the `url` is the portal’s endpoint, which the MCP connector cannot reach.
A tool returns `scope_required`	The token was not approved for that tool’s scope. Revoke the token and sign in again, approving the scope (Scopes, per tool).
A tool reports that the role does not allow it	The tool requires a role the person does not hold, such as `client_admin` for billing.

See also Connect a client and MCP security.