LuaMCPServer instead (see Use an MCP server).
Verified against lua-cli 3.33.0.
Before you begin
- A connection made with
lua integrations connect.
1
List the servers
Every agent-scope connection has one MCP server, named after the integration type and activated when the connection is finalized.
Output
lua mcp list shows the same servers next to the ones you declared, with their Unified.to URL, which carries the connection ID and any scopes chosen at connect time.2
Know what the model sees
Each tool is exposed as
<server>_<tool>: <server> is the server name (linear, googlemail; a second account of the same type gets a generated prefix) and <tool> the operation Unified.to publishes for that type, so tools from two connections never collide. Every active connection also gets one <type>_passthrough tool, with which the model can make a raw API call to the provider through the same relay as Integrations.passthrough. The connection’s account label is prepended to every tool description, as data, so the model can tell two accounts apart. The scopes chosen at connect time bound the operations, and --hide-sensitive true removes PII fields from results.The CLI doesn’t print individual tool names; ask in a chat instead.3
Deactivate or activate
Deactivating hides the tools from the model on its next turn; the connection, its credential, and its integration webhooks stay.
lua mcp deactivate --server-name linear and lua mcp activate --server-name linear do the same by server name.4
Verify
lua integrations list reports the switch as Active with (active), or Connected (MCP pending) with (inactive).Output
Options you may need
Integration servers and your own LuaMCPServer
- Provisioning: an integration’s server is created, hosted, and activated by the platform when you connect, and deleted when you disconnect. Yours is declared in code, pushed with
lua push mcp, and switched withlua mcp activate; both kinds are unversioned, so a push replaces the server in place. - Credentials: the platform holds the integration’s OAuth grant or token, and your code never sees it. For your own server you supply the URL and headers.
- Naming: both kinds expose tools as
<server>_<tool>, where<server>is the integration type for an integration’s first account and the name you declared for your own server. - Spaces: in a Space, an integration’s tools are offered only when the end user talking to the Space may use that connection (their own, or one shared with the organization); if that check can’t be made, the tools are left out of the turn. Your own servers are agent-level and always available.
If it isn’t working
❌ Missing required option: --connection <id>
❌ Missing required option: --connection <id>
activate and deactivate need the connection ID, and this line exits 0, so a script can’t rely on the exit code. Take the ID from lua integrations mcp list.❌ No MCP server found for connection: …
❌ No MCP server found for connection: …
The ID doesn’t belong to this agent, or the connection has no server yet. Check
lua integrations list; a status of Connected (MCP pending) means the server exists but is inactive, so run activate with the ID shown there.The tools are active but the model doesn't use them
The tools are active but the model doesn't use them
The persona and the skill
context decide when the model calls a tool. Name the integration in the persona (“Use the Linear tools for issue questions”) and test with lua chat; see About skills and tools.Next steps
Call an integration's API directly
What the
<type>_passthrough tool does, from your own code.Subscribe to integration events
Let the provider wake the agent.
About MCP servers
How MCP tools reach the model.
lua mcp reference
The server-level commands.