Read time: ~8 minutes · Series: Platform Admin (Data Engineering) advanced · Previous: .lantide export / import · Next: MCP Sources basics
Two directions that both say “MCP”
When the team says “we want MCP,” they may mean two completely different things:
| Direction | Lantide’s role | Where you configure it | Purpose |
|---|---|---|---|
| Agent Integration | MCP server | Top-right Agent Integration | Let Cursor, Codex, Claude, or similar Agents read or operate the Lantide work environment |
| MCP Sources | MCP client | Sidebar MCP Sources | Materialize external APIs or data services into queryable tables |
This article covers the first: letting an external Agent connect into Lantide. If you need to bring data in, read MCP Sources basics. Both use MCP, but the connection direction, permissions, and troubleshooting differ.
An external Agent in Execute mode can call the shared MCP Source controls through Lantide (for example explore, pull, test, and connect). Admin is required to add a source, replace credentials, or remove it. Observe may read materialized tables and schema only; it cannot call the remote source.
When Agent Integration is worth enabling
Good fit:
- Analysts already work in Cursor, Codex, or Claude and want to keep that chat surface.
- The team still requires Plan, SQL evidence, Report, and Activity to live in Lantide.
- You need a local Agent entry point you can inspect, constrain, and revoke—not handing data and credentials to a remote API.
You can skip it when:
- The team only uses Lantide’s built-in Agent.
- You only need Lantide to read an external API—that is MCP Sources.
- The external Agent runs on another machine or in the cloud. Agent Integration binds to local loopback; it is not a remote shared API.
Step 1: Choose Quick or Persistent
When a supported local Codex flow opens Agent Integration, you can use Approve & Connect instead of manually copying a connection kit. Review the scope, mode, expiry, exposure, and local config destination in the GUI; Lantide creates the credential and merges the Codex MCP setting only after that approval. The credential is not shown in chat or a deep link.
| Choice | Best for | Remember |
|---|---|---|
| Quick connection | One-off tests scoped to the current workspace | Switching workspaces does not retarget the same config; re-Expose yields a new config |
| Persistent connection | Regular use of the same external Agent across App restarts | The token appears only once after Create or Rotate; after a normal restart the client must initialize again |
If you only want to confirm the client can connect, start with Quick. For day-to-day work, a Persistent connection with a clear alias, expiry, and scope is easier to govern than pasting one-off configs repeatedly. The first tools/list is a stable compact catalog; after an All-workspaces connection binds, call get_analysis_context without re-listing tools. Use search_capabilities and its guarded read/write invokers for long-tail capabilities.
Step 2: Choose trust level before mode
Access mode is this connection’s capability ceiling, not a Plan analysis phase.
| Mode | Capabilities | Who should start here |
|---|---|---|
| Observe | Read-only workspace and artifacts; no writes; does not pause the built-in Agent | First evaluation, accompanied review, low-trust exploration |
| Execute | Can create analysis artifacts; formal queries still follow Plan review, evidence, and Report contracts | Analysts completing formal analysis in one clear workspace via an external Agent |
| Admin | Execute plus high-trust workspace, project, knowledge, alias, and local delivery operations | Trusted Agents that must help tidy the environment or finish admin tasks |
The Create connection form currently defaults to All workspaces + Admin. That is a form default, not a recommendation to grant maximum privilege on first try. Split by purpose:
- Low trust or first evaluation: Observe—confirm it can see the right workspace and artifacts.
- Formal analysis: Single workspace + Execute—lock the data boundary to one workspace so Plan, Approve & Execute, evidence, and Report leave a full trail.
- High-trust environment management: Admin—only after you trust the Agent, its scope, and how you will review work.
Admin does not mean “more professional,” and it does not skip Plan or deliverable review; it only allows more local operations.
Step 3: Single workspace or All workspaces
| Scope | Modes available today | Best for |
|---|---|---|
| Single workspace | Observe / Execute / Admin | Work boundary already clear; prefer this for formal analysis |
| All workspaces | Observe / Execute / Admin | Agent must compare workspaces first, then pick one explicitly; it does not mean operating many workspaces at once |
An all-workspaces connection starts unbound on every initialize:
- Observe after selecting a workspace does background read-only exploration; it does not switch the Lantide GUI or displace an existing writer.
- Admin after selecting a workspace takes writer ownership for that workspace and may switch the GUI to it.
- If another Execute / Admin session is already writing, the system does not silently seize it. The external Agent must explain the blocker and risk, get your consent, then retry against that session.
To move to another existing workspace, use an all-workspaces profile; do not let the Agent create a new workspace to fake a switch.
Exposed, active, and selected are not the same
| UI state | Meaning |
|---|---|
| Profile is Exposed | The endpoint can accept a client; a session is not necessarily established |
| External session observing (blue) | Observe session active; built-in Agent still usable |
| External agent mode enabled (green) | Execute / Admin writer active; built-in Agent paused in that workspace |
| All-workspaces unbound | Client connected but no workspace selected yet |
| Activity shows Ended | History remains; the Agent is not necessarily still connected |
If a profile is Exposed but the header shows no status, confirm the client reloaded MCP and initialized successfully—do not treat waiting as disconnect, or old Activity as active.
How to accept an external Agent’s work
“I’m done” in the external chat is not acceptance criteria. Check in order:
- Artifacts—expected Plan, SQL, and Report actually exist.
- Plan lifecycle—formal analysis went through Approve & Execute, not exploration treated as official numbers.
- Evidence—key figures trace back to formal query steps.
- Report—answers the question, includes concrete numbers and limitations.
- External MCP Activity—actual calls, affected files, and
+N/-Nmatch expectations. - Audit / Save History—high-trust operations and local delivery left corresponding records.
Content changes that support safe rollback show Undo in Activity. Revert is allowed only while the file has not been modified further; if content changed, the system blocks instead of force-overwriting. Reverting a newly created file clears content but keeps the file; side-effecting operations such as Plan lifecycle, export, connections, and knowledge governance cannot be undone from Activity.
Activity privacy and retention
Activity stores redacted host facts, artifact identity, and line-count stats—not the external chat transcript, and not tokens or full change bodies in activity events.
- Archive: hides ended sessions from the day-to-day list only.
- Clear archived/ended history: actually deletes matching Activity and related Undo snapshots.
- Clearing Activity does not delete active sessions, business audit, Plan, Report, or knowledge.
For configuration details and full button steps, see USER_GUIDE §13.7.
Safety floor
- The MCP host binds only to local
127.0.0.1; do not share the config as a remote API. - Put the bearer credential only in a local MCP client you trust—never paste it into issues, public chat, or a team wiki.
- Unexpose pauses the endpoint; Rotate invalidates the old token immediately and requires an updated client config; Revoke permanently retires the profile.
- A Persistent token appears once; store it in an appropriate local secret/config location at create time.
- Solo Admin work is an advanced practice. If you are not watching Lantide live, still review artifacts, Activity, and audit afterward.
Full setup, window-close, and recovery steps: USER_GUIDE §13.
First-trial checklist
- Confirm you are using Agent Integration, not MCP Sources
- Create an expiring connection against a test workspace
- For low-trust evaluation, start with Observe and confirm the built-in Agent still works
- For formal analysis, use a separate Single workspace + Execute connection
- In Lantide, verify Plan, evidence, Report, and External MCP Activity
- Practice interrupting the session; confirm the profile can Expose and initialize again
- Confirm who may Rotate / Revoke, and who owns Approve & Execute
Next steps
- MCP Sources basics—read when Lantide needs to pull data in
- Backup, security boundaries, and common issues
- Analyst: Plan → annotate → Execute → Report
- Platform Admin (Data Engineering) introduction