# Use LightHouse in Claude > Configuration of LightHouse's MCP server in Claude on the web, the desktop and mobile apps, Claude Code, the Claude API and the Claude Agent SDK. 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](#claude-on-the-web-and-in-the-desktop-app) | OAuth, at the hosted endpoint | | Claude Code | [`claude mcp add`](#claude-code) | OAuth at the hosted endpoint, or a machine key at the portal’s endpoint | | An application on the Claude API | [The MCP connector](#the-claude-api-mcp-connector) | An OAuth token, at the hosted endpoint | | An application on the Claude Agent SDK | [`mcp_servers`](#the-claude-agent-sdk) | 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](/mcp/connect/#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](/api/authentication/)). | The hosted endpoint, used throughout this page: ```text https://mcp.atlanticagenticlabs.com/t//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. 1. Go to **Organization settings → Connectors**. 2. Select **Add**, then **Custom**. If Claude asks for the connector type, choose **Web**. 3. Enter the name `LightHouse` and the hosted endpoint’s address, with the tenant ID in place of ``. 4. 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. 5. 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 1. Go to **Customize → Connectors**. 2. Select **Add**, then **Add custom connector**. 3. Enter the name `LightHouse` and the hosted endpoint’s address, then select **Continue**. 4. Keep the options Claude marks **Detected**, choose **Register automatically** for the OAuth client, and select **Add**. 5. Select **Connect** and sign in ([Sign in](#sign-in)). The Free plan allows one custom connector. ### Sign in 1. Select **Connect** on the LightHouse connector. Result: the browser opens the portal’s approval page, `https://.atlanticagenticlabs.com/oauth/authorize`. If the portal requires it, sign in through the identity provider. 2. 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 1. Claude to MCP endpoint: **First request, no token** 2. MCP endpoint to Claude: **Refused, naming where to sign in**. the endpoint's protected-resource document names the portal 3. Claude to Tenant portal: **Register**. dynamic registration: an identifier, no secret Approval 4. Claude to Tenant portal: **Open the approval page**. with a PKCE challenge (S256) 5. Tenant portal to Person: **Who is asking, where the answer goes, each scope**. after sign-in with a second factor 6. Person to Tenant portal: **Approve**. recorded in the tenant's audit log 7. Tenant portal to Claude: **A single-use code**. bound to the client and its redirect 8. Claude to Tenant portal: **Code and verifier for a token**. one tenant, one person, the approved scopes Use 9. Claude to MCP endpoint: **Tool call, with the token**. read-only tools 10. 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 1. In a conversation, select **+**, then **Connectors**, and confirm that LightHouse is on. 2. 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](/mcp/#read-only-deliberately)). ## Claude Code ### With OAuth 1. Add the hosted endpoint: ```bash claude mcp add --transport http lighthouse "https://mcp.atlanticagenticlabs.com/t//mcp" ``` 2. 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. 3. 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](/mcp/connect/#with-a-machine-key)): ```bash 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__`, 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](/mcp/#signing-in-with-oauth)). Refresh the token when it expires and send it with every request. ```bash 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//mcp", "name": "lighthouse", "authorization_token": "'"$LIGHTHOUSE_TOKEN"'" } ], "tools": [ { "type": "mcp_toolset", "mcp_server_name": "lighthouse" } ] }' ``` In Python: ```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//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: ```python 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`: ```ts 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 "}`. The SDK does not open a browser or run a sign-in. The application obtains the token as described for the [MCP connector](#the-claude-api-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](/mcp/connect/#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](/mcp/#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](/mcp/connect/) and [MCP security](/security/mcp/). Source: https://docs.atlanticagenticlabs.com/mcp/claude/