External AI Agents & MCP Server

13. External AI Agents & MCP Server

Lantide Data can also act as a local MCP Server, letting your preferred external AI Agent (for example Cursor, Codex, Claude, or any other client that supports Streamable HTTP MCP) work directly with Lantide's data environment and analysis surface.

An external Agent does not replace Lantide's GUI: it collaborates with you in its own conversation, while Lantide preserves reviewable Plans, Reports, SQL / evidence, approvals, Save History, audit, and a record of the Agent's actual MCP calls. This lets you cross-check "what the Agent says it did" against "what Lantide actually recorded."

Do not confuse this with the MCP Sources in §4.6. MCP Sources is Lantide acting as an MCP client to connect to external data or APIs; the MCP Server in this section is Lantide acting as an MCP server that external AI Agents connect into.

13.1 When to Use It

Choosing external Agent integration usually means you already work inside some external Agent but want your analysis to go beyond the chat log:

• You want the Agent to analyze local data while keeping the Plan, Report, and formal evidence in Lantide.
• You want to keep your usual workflow in Claude / Codex, but review execution, results, and the activity trail in Lantide.
• You want a high-trust Agent to help organize workspaces, projects, document aliases, or knowledge, while keeping the GUI, audit, and traceable artifacts.

If you only need to complete analysis inside Lantide, just use the built-in AI assistant; there is no need to set up an MCP connection.

13.2 Turning On Agent Integration

1. Click the Server Cog icon in the top-right of the main screen to open Agent Integration. The Persistent connections tab opens by default.
2. Turn on Enable MCP server at the top. This is a global switch that controls both Quick and Persistent connections.
3. Create a reusable connection under Persistent connections, or switch to Quick connection to create a one-off connection bound only to the current workspace.

One-click Codex pairing: When Agent Integration is opened from a supported local Codex flow, Lantide can prefill a pairing request. Review the scope, access mode, expiry, exposure, and local config destination, then choose Approve & Connect. Only that approval creates the credential and merges the Codex MCP configuration; the credential is never shown in chat, a deep link, a command line, or the clipboard. If writing the configuration fails, use a one-time connection kit instead.

Turning off the global switch immediately stops all inbound MCP endpoints and unexposes both Quick and Persistent connections; saved Persistent profile settings are not deleted. When you turn the global switch back on later, Persistent connections that are still valid and set to exposed become available again.

Security note: Lantide's MCP host binds only to the local 127.0.0.1. The connection config contains a bearer credential—paste it only into MCP client settings on machines you trust; never paste it into public chat rooms, issues, or remote hosts. An external Agent cannot request or rebuild your credential on its own.

13.3 Quick connection: A One-Off Connection for the Current Workspace

A Quick connection suits a single analysis, temporary external Agent use, or when you only want to hand over the current workspace.

1. Switch to the workspace you want to use.
2. Choose an Access mode on the Quick connection tab.
3. Click Expose host. Lantide creates a new connection credential in the same step.
4. Click the Copy icon next to the connection config and paste the JSON config into the external Agent's MCP settings.
5. Return to the external Agent, reload MCP or start a new conversation, and let it initialize.

A Quick connection's credential is delivered only through the copied content; it is not shown again after you leave this screen. If you lose the config, Unexpose and then Expose again to get a new one. A Quick connection is workspace-scoped; switching workspaces does not automatically repoint the same config to the new workspace.

13.4 Persistent connection: A Connection That Survives Restarts

A Persistent connection suits frequent use of the same external Agent, or when you want to keep an authorized local host even after closing the Lantide window.

1. Switch to Persistent connections and click Create connection. The current creation screen defaults to All workspaces + Admin; this is only a form default and does not mean Admin is right for every case. For a first evaluation or low-trust read-only exploration, start with Observe; for single-workspace analysis that needs Plan review and formal evidence, choose Execute.
2. Enter a recognizable Alias, such as "My Codex analysis connection."
3. Choose an Access mode and Connection scope:

• Single workspace: Select one required workspace; the connection binds to it automatically once connected. Access mode can be Observe / Execute / Admin.
• All workspaces: Can be paired with Observe, Execute, or Admin. Each connection starts unbound, so the Agent explicitly selects one workspace before workspace-bound work.

4. Choose an expiry (1 / 3 / 7 / 30 / 180 / 365 days or Permanent) and decide whether to Expose immediately.
5. After creating, copy the JSON config shown once and save it to your MCP client.

A Persistent config uses an installation-level stable local URL; after a normal Lantide restart, a profile that is exposed, not expired, and not revoked can re-initialize with the same config. The token is shown only once after creation or Rotate; the profile list does not echo the token.

If the stable port is taken by another program, Persistent connections shows a warning that may include an identifiable PID / process name. After freeing the port, click Retry—no need to restart Lantide; Retry does not change the URL. Only using Change local MCP port yourself changes the URL.

13.5 Access mode: The Connection's Capability Ceiling, Not an Analysis Phase

Access mode is chosen by you when creating a connection or Quick connection. It is the capability ceiling of what the external Agent can do; it does not switch automatically when a Plan moves from planning to executing.

New Quick / Persistent connections offer only these three modes. Draft is discontinued and is no longer offered as an option for new connections; external Agents should not recommend Draft either.

A Plan's Approve & Execute only approves that Plan's execution scope and evidence context; it does not automatically upgrade or downgrade the connection between Observe / Execute / Admin. Conversely, an external Agent cannot raise its own access mode or enable the global MCP server through MCP.

13.6 Three Recommended Working Styles: Not New Modes

Access mode is a hard capability boundary; the following are working styles that Lantide recommends external Agents adopt based on the task and your preferences. After connecting, an external Agent reads the playbook and should explain the current connection's scope, capabilities, and recommended approach.

These three are not a third mode in the settings page, nor do they restrict you from changing how you work. On an Admin connection the external Agent usually recommends dual-window first; if you only say "less interruption" or are unsure, it should ask whether you want to watch Lantide in real time or review later—a low-interruption preference alone is not enough to switch to single-window. Single-window is an advanced working style: it does not mean you can skip Lantide's way of recording analysis; the in-the-moment review happens in the external conversation, and when you review later, the artifacts and Activity / audit you see in Lantide should be just as complete as with dual-window. If you are unsure, simply tell the external Agent your goal and preferences, or ask: "What can this connection do right now? How should I use Lantide?"

13.6.1 When an External Agent Creates Workspaces, Projects, or Switches Focus

An external Agent should first read existing projects, artifacts, and the current focus before explaining its organizational decisions to you. It should not create workspaces / projects in bulk just because of a new chat, a temporary lack of activity, or a preference for tidiness.

13.6.2 Compact catalog and capability search

The first tools/list returns a stable compact catalog for the connection's access mode. Core tools can be called directly. For a long-tail HTML or statistical capability, the Agent searches search_capabilities with one concise English action-and-object request, then uses the returned guarded read or write invoker with the exact capability ID and descriptor digest. Search does not execute a capability, and neither invoker bypasses access mode, confirmation, evidence, Activity, or audit. After select_workspace, the Agent calls get_analysis_context; it does not reload the tool list.

13.7 Reviewing an External Agent's Work in the GUI

The Header shows the backend-confirmed active session, not the "Exposed" configuration state:

• Observe session: The top shows a blue External session observing. Observe is a read-only connection; it does not take writer ownership, and the built-in Lantide Agent remains usable.
• Execute / Admin writer session: The top shows a green External agent mode enabled. This means the current workspace is operated by an external writer session, and the built-in Lantide Agent pauses to avoid two Agents modifying the same analysis context at once.
• Exposed waiting: The endpoint/profile can accept connections but has no active session yet; the Header does not show it as connected. Check Agent Integration for configuration states such as exposed, recovery, or conflict.

The sidebar workspace row shows an MCP status icon only when that workspace has an active external session: Observe uses a blue dot, Execute / Admin use a green dot. It is a quick hint about current work; the full connection settings, waiting, and error handling still come from Agent Integration.

• Click the Header pill or Manage in the AI panel to open Agent Integration.
• The link-off icon on the right of the pill means "disconnect the current session." It ends the current external MCP conversation and asks the client to re-initialize, but does not unexpose the Quick connection, nor revoke the Persistent profile or token.
• To truly stop a Quick connection, click End external agent mode / Unexpose on the Quick tab; to stop a Persistent connection, turn off that profile's Expose switch.

The External MCP Activity in the right panel is an observation and reconciliation surface that lets you confirm what the Agent actually called, what it changed, and—when the safety conditions hold—roll back an individual content change:

• Each external connection creates a logical session; the title shows the profile alias (or Quick connection), the workspace, and Active / Ended status. Activity history can retain finished work, but that does not mean the session is still active.
• Cards are added top to bottom in time order, recording initialize, resource read, tool call, policy / review results, and connection end. Click a card to expand the redacted security summary.
• Each successful content mutation forms its own Activity card; the system does not guess external conversation turns by time, nor pass off multiple tool calls as one operation. Below the card it persistently shows the affected SQL, Plan, Report, Reference, or HTML artifact, with green +N / red -N line counts. Click the filename to open the artifact; if it belongs to another workspace, the system asks you to switch first instead of creating a wrong, blank tab.
• Changes that support safe rollback show an Undo icon on the right. After you confirm Revert, the system rolls back only that content mutation; before rolling back it verifies the current content still equals the after hash recorded at the time. If someone—or another Agent—has since modified it, a content conflict blocks the action, and no force revert is offered.
• Reverting a newly created file clears its content but keeps the file. Operations with side effects—Plan lifecycle, execution completion, lineage, export, workspace / connection mutation, knowledge governance, and so on—cannot be reverted from Activity. After a successful revert, the original Activity remains and is marked as reverted; the system appends a revert activity and audit—it does not delete the original history.
• History (the clock icon to the right of the title) switches among past sessions; a blue dot only means that session has non-session-end activity you have not yet seen (disconnect / restart endings themselves do not count), not that the connection is still active. The blue dot sits right after the profile name. Mark all as read at the top of the list clears all blue dots at once. An Ended session can be Archived (hidden from the list but kept until the retention period expires).
• The External MCP activity icon in the right icon strip shows a red dot when there is unseen attention activity while the panel is collapsed; opening the Activity panel hides the red dot (unread is then indicated by the History blue dot).
• Activity content redacts bearer credentials, tokens, and sensitive content that should not appear in an observation panel. Activity is not the external Agent's chat log and does not store the body of changes; the restricted before/after snapshots needed for Undo are stored separately on your machine.
• The gear icon to the left of History in the title bar opens Activity retention and privacy:
  • Set Max events per session and Ended session retention from the dropdowns; saving immediately prunes overly old sessions and compresses the event count.
  • Clear archived history (N) deletes only Archived history; Clear ended history (N) deletes all ended history (including Archived ones). The parentheses show how many sessions each will delete; both also delete the related Undo snapshots and do not clear active sessions.
  • The above cleanup does not affect business audit, artifacts, or knowledge. Setting changes and Clear are written to the local host-level admin audit, and no sensitive body is written into Activity events.

An external Agent can open, focus, or refresh the relevant Plan / Report / SQL tabs. You should still rely on the artifacts, Plan steps, Report, Save History, Activity, and audit that actually appear in Lantide as the basis for results, rather than the Agent's spoken account in the external chat.

13.8 Plans, Approvals, Evidence, and Admin Operations

The analysis flow on an Execute connection is usually: the Agent creates or revises a Plan → requests a GUI review → you click Approve & Execute in the existing Plan toolbar → the Agent obtains that Plan's execution scope → and runs formal queries and produces the Report continuously within scope. You do not need to reconfirm every formal SQL statement in the Plan.

Formal evidence is kept in the Plan's execution progress. Exploratory queries not tied to a Plan can exist, but should not be treated as key numbers in a Report. If a Report needs supplementary data after it is produced, the Agent can link a post-execution action to the Report so Lantide shows this as supplementary evidence outside the formal steps; when editing a Report it can also link back to the corresponding evidence.

Admin operations are confirmed differently depending on the connection mode:

• On an Execute connection, Admin-level operations appear in the pending approval notification at the top. You can Approve / Reject each one, or choose to Approve all in order; the backend applies changes only after approval.
• On an Admin connection, Lantide does not ask for GUI confirmation on each Admin operation. The external Agent still receives a security warning and should get your consent in its own conversation first; all operations still leave an audit and Activity.

For result export, the Agent first stages the full result and confirms staging is complete before submitting a review or a direct-save. Execute is usually approved by you in the GUI or via Save; an Admin direct-save writes to a confirmed destination that the Agent cannot arbitrarily swap, and leaves a warning / audit. You can check statuses such as Preparing, Ready to save, Saved, failed, or expired in the right-side Save History; a manual Results export still uses the original local file selection flow.

13.9 Selecting and Switching in All workspaces

An All workspaces profile (Observe, Execute, or Admin) starts unbound after each external Agent initialize; it does not silently reuse the previous workspace. The compact catalog stays stable; before workspace-bound work, the Agent explicitly selects one workspace and then reads get_analysis_context.

Observe (All workspaces)

• After selecting a workspace it can do read-only exploration; it does not take writer ownership, and does not switch the Lantide GUI's current workspace.
• It can coexist with an existing Execute / Admin writer session; it does not require eviction just because the target workspace is already occupied.
• It cannot create new workspaces (create_workspace_and_select is Admin-only).

Admin (All workspaces)

• After successfully selecting or creating a workspace, the same MCP session binds to it; Lantide switches the current active workspace accordingly and refreshes the sidebar and that workspace's services.
• The same profile can hold only one Admin writer workspace at a time.
• If the target workspace is already used by another writer connection, the Agent sees occupancy information. It must first get your consent in the external conversation and resubmit the switch with the specified session; the system does not silently preempt. A session you agree to evict ends, but that profile's expose / token settings remain.

Execute (All workspaces) follows the same one-writer-at-a-time rule for formal analysis. It remains subject to GUI Approve & Execute for the Plan; selecting a different workspace revokes the prior workspace's execution grant and pending reviews.

If you are currently using a Single workspace connection but need to move to another existing workspace, go to Agent Integration to create or switch to an All workspaces profile—do not ask the Agent to fake a switch by creating a new workspace.

13.10 Closing the Window, Reopening, and Explicit Exit

If an exposed Persistent connection or an exposed Quick connection exists, closing the Lantide window does not necessarily stop the host: Lantide can keep the backend and MCP listener running in the background so an authorized external Agent is not interrupted unexpectedly, while destroying the renderer to reduce front-end resource use.

• macOS: Reopen the window from the Dock.
• Windows: If there is a connection worth keeping, the window can collapse to the system tray; the first time you close it with no keep condition, it asks whether to quit directly or keep it in the tray, and can remember your choice.
• If there is unsaved content, a confirmation appears first: Close window and discard or Cancel.
• Quit Lantide, an app update, a crash, or a system termination stops the backend / listener; subsequent external client requests fail closed. On the next launch, only valid Persistent profiles set to exposed are restored, and clients must re-initialize.

13.11 Common Questions and Safety Checks

Why can't the external Agent connect?

First confirm the global Enable MCP server is on, the relevant Quick / Persistent connection is exposed, and the token is not expired / revoked. When the Persistent listener shows a port collision, free the occupying program first and then click Retry; do not change the config to another port yourself. If you deliberately Change local MCP port, you must update the URL saved in the external client.

Why does the external Agent need to re-initialize?

This is expected safety semantics: an app restart, Rotate, Revoke, Unexpose, global disable, an explicit Disconnect session, or a workspace eviction all invalidate the old session. Re-initializing creates a new MCP session; this does not mean you need to recreate the profile or get a new token (except for Rotate / Revoke).

Why can't I type in the built-in AI panel?

The built-in Agent pauses to avoid conflicts only when an active Execute / Admin writer session exists in the current workspace. An active Observe session does not block the built-in Agent. If the Header shows the green external writer state, let the external Agent finish, use link-off to disconnect the session, or end / unexpose the external connection before using the built-in Agent.

My old Activity cards are still there—does that mean the Agent is still connected?

No. Activity history is a traceable record; check the session's Active / Ended indicator. You can archive an ended session to hide its everyday list item without deleting the underlying audit.

Why does the Header show no external session even though the connection is Exposed?

Expose only means the endpoint/profile can accept external clients, and it may still be in exposed waiting. Only after the client reloads MCP and initializes successfully does the Header show an active Observe or writer session. If no session is established for a long time, check the global switch, profile expiry/revocation, port status, and client config in Agent Integration.

What should I do about recovery or writer conflict?

Persistent problems stay in Agent Integration, the Header, or the relevant status surface—not just a brief Toast. Use the primary action offered on screen: Retry, Disconnect session, Unexpose, Rotate credential, Select workspace, or Resolve conflict. A Workspace conflict first shows the blocking writer session; only after you explicitly consent in the external conversation can the Agent specify that session and retry—the system does not silently evict or disable the other party's profile. Diagnostic details can keep an error code for reporting, but you do not need to manually edit the sidecar or guess the raw MCP state.

Can I give the Persistent config to a colleague or a remote service?

Not recommended. It is a local loopback endpoint with a local bearer credential; it is designed for a trusted MCP client on your own computer, not a remotely shared API. To let someone else use it, create their own connection on their Lantide installation.

Operational note: If you hit connection, recovery, or client compatibility issues, keep the credential-free error code, an Activity screenshot, and reproduction steps, then report per §21.