> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage integration MCP tools

> See which tools a connection gives the model, and activate or deactivate them without touching the connection

After this guide, you know which tools a connected [integration](/concepts/integrations) adds to the model, how they are named, and how to switch them off and on. A connection's tools arrive as an [MCP server](/concepts/mcp-servers) the platform provisions and hosts; for a server you host yourself, declare a `LuaMCPServer` instead (see [Use an MCP server](/build/use-an-mcp-server)).

*Verified against lua-cli 3.33.0.*

**Before you begin**

* A connection made with [`lua integrations connect`](/integrations/connect).

<Steps>
  <Step title="List the servers">
    Every agent-scope connection has one MCP server, named after the integration type and activated when the connection is finalized.

    ```bash theme={null}
    lua integrations mcp list --ci
    ```

    ```text Output theme={null}
    ────────────────────────────────────────────────────────────────────────────────
    🔌 MCP Servers for Connections
    ────────────────────────────────────────────────────────────────────────────────

      Connection: 6aa54baaaedc9ab702656392
      Integration: GitHub
      MCP Server: github
      Status: ✅ active
    ────────────────────────────────────────────────────────────────────────────────
      Connection: 6aa3c41eecbe5884460c797c
      Integration: Linear
      MCP Server: linear
      Status: ✅ active
    ────────────────────────────────────────────────────────────────────────────────
    …
    Total: 3 connection(s)
    ```

    `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.
  </Step>

  <Step title="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`](/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.

    ```bash theme={null}
    lua chat -m "Which Linear tools do you have?"
    ```
  </Step>

  <Step title="Deactivate or activate">
    Deactivating hides the tools from the model on its next turn; the connection, its credential, and its integration webhooks stay.

    ```bash theme={null}
    lua integrations mcp deactivate --connection 6aa3c41eecbe5884460c797c --ci
    lua integrations mcp activate --connection 6aa3c41eecbe5884460c797c --ci
    ```

    `lua mcp deactivate --server-name linear` and `lua mcp activate --server-name linear` do the same by server name.
  </Step>

  <Step title="Verify">
    `lua integrations list` reports the switch as `Active` with `(active)`, or `Connected (MCP pending)` with `(inactive)`.

    ```bash theme={null}
    lua integrations list --ci
    ```

    ```text Output theme={null}
    …
    🟢 Linear
       Connection: 6aa3c41eecbe5884460c797c
       Status: Active
       MCP Server: linear (active)
       Connected: 11/09/2026
    …
    ```
  </Step>
</Steps>

## 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 with `lua 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](/concepts/spaces), 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

<AccordionGroup>
  <Accordion title="❌ 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`.
  </Accordion>

  <Accordion title="❌ 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.
  </Accordion>

  <Accordion title="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](/concepts/skills-and-tools).
  </Accordion>
</AccordionGroup>

## Next steps

<Columns cols={2}>
  <Card title="Call an integration's API directly" href="/integrations/passthrough">What the `<type>_passthrough` tool does, from your own code.</Card>
  <Card title="Subscribe to integration events" href="/integrations/events">Let the provider wake the agent.</Card>
  <Card title="About MCP servers" href="/concepts/mcp-servers">How MCP tools reach the model.</Card>
  <Card title="lua mcp reference" href="/reference/cli/mcp">The server-level commands.</Card>
</Columns>