> ## 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.

# MCP Command

> Manage MCP servers for your agent

## Overview

The `lua mcp` command manages Model Context Protocol (MCP) servers. Use it to list, activate, deactivate, and delete MCP servers.

<Note>
  **MCP servers from integrations**: When you connect a third-party account via `lua integrations connect`, an MCP server is automatically created and activated. These integration-based servers have a `source` field set to `unifiedto`. You can manage them with both `lua mcp` and `lua integrations mcp` commands.
</Note>

```bash theme={null}
lua mcp              # Interactive mode
lua mcp list         # List all servers
lua mcp activate     # Activate a server
lua mcp deactivate   # Deactivate a server
lua mcp delete       # Delete a server
```

### Non-Interactive Mode

```bash theme={null}
# List all MCP servers
lua mcp list

# Activate a server (positional or flag style)
lua mcp activate docs-server
lua mcp activate --server-name docs-server

# Deactivate a server
lua mcp deactivate --server-name api-server

# Delete a server
lua mcp delete --server-name old-server
```

| Option                 | Description                                      |
| ---------------------- | ------------------------------------------------ |
| `--server-name <name>` | MCP server name (for activate/deactivate/delete) |

| Action       | Description          | Required Options              |
| ------------ | -------------------- | ----------------------------- |
| `list`       | List all MCP servers | None                          |
| `activate`   | Activate a server    | `--server-name` or positional |
| `deactivate` | Deactivate a server  | `--server-name` or positional |
| `delete`     | Delete a server      | `--server-name` or positional |

## Commands

### lua mcp

Interactive MCP server management.

```bash theme={null}
lua mcp
```

Opens an interactive menu to:

* List MCP servers
* Activate a server
* Deactivate a server
* Delete a server

### lua mcp list

List all MCP servers and their status.

```bash theme={null}
lua mcp list
# or
lua mcp ls
```

**Output:**

```
============================================================
🔌 MCP Servers
============================================================

✅ Active Servers:

🟢 docs-server
   Transport: streamable-http
   URL: https://docs.example.com/mcp
   ID: mcp_abc123

────────────────────────────────────────

⏸️  Inactive Servers:

⚪ api-gateway
   Transport: streamable-http
   URL: https://api.example.com/mcp
   ID: mcp_def456

============================================================
```

### lua mcp activate

Activate an MCP server to make its tools available.

```bash theme={null}
lua mcp activate              # Interactive selection
lua mcp activate docs-server  # Activate by name
# or
lua mcp enable docs-server    # Alias
```

**What happens:**

* Server is marked as active
* Server's tools become available to your agent
* Tools appear in the agent's tool list at runtime

**Example:**

```bash theme={null}
$ lua mcp activate docs-server
🔄 Activating docs-server...

✅ MCP server "docs-server" activated successfully!

💡 The server's tools are now available to your agent.
```

### lua mcp deactivate

Deactivate an MCP server to remove its tools.

```bash theme={null}
lua mcp deactivate              # Interactive selection
lua mcp deactivate docs-server  # Deactivate by name
# or
lua mcp disable docs-server     # Alias
```

**What happens:**

* Server is marked as inactive
* Server's tools are removed from agent runtime
* Configuration is preserved (can be re-activated)

**Example:**

```bash theme={null}
$ lua mcp deactivate docs-server
🔄 Deactivating docs-server...

✅ MCP server "docs-server" deactivated successfully!

💡 The server's tools are no longer available to your agent.
```

### lua mcp delete

Permanently delete an MCP server.

```bash theme={null}
lua mcp delete              # Interactive selection
lua mcp delete docs-server  # Delete by name
# or
lua mcp rm docs-server      # Alias
```

<Warning>
  **This is permanent!** Deleting an MCP server removes it from the platform. You'll need to re-compile and push to recreate it.
</Warning>

**Example:**

```bash theme={null}
$ lua mcp delete docs-server

⚠️  You are about to delete MCP server: docs-server
⚠️  WARNING: This server is currently ACTIVE!
? Are you sure you want to delete this MCP server? (y/N) y

🔄 Deleting docs-server...

✅ MCP server "docs-server" deleted successfully!
```

## Command Aliases

| Command              | Alias             |
| -------------------- | ----------------- |
| `lua mcp list`       | `lua mcp ls`      |
| `lua mcp activate`   | `lua mcp enable`  |
| `lua mcp deactivate` | `lua mcp disable` |
| `lua mcp delete`     | `lua mcp rm`      |

## Pushing MCP Servers

MCP servers can also be pushed using the `lua push` command:

```bash theme={null}
# Push a single MCP server
lua push mcp
# Select server from list

# Push all components including MCP servers
lua push all --force
```

When pushing all with `--auto-deploy`, MCP servers are automatically activated:

```bash theme={null}
lua push all --force --auto-deploy
```

## Workflow Example

<Steps>
  <Step title="Define MCP Server">
    Create the server in your code:

    ```typescript theme={null}
    // src/mcp/docs.ts
    import { LuaMCPServer, env } from 'lua-cli';

    export const docsServer = new LuaMCPServer({
      name: 'docs-server',
      transport: 'streamable-http',
      url: 'https://docs.example.com/mcp',
      headers: () => ({
        'Authorization': `Bearer ${env("DOCS_API_KEY")}`
      })
    });
    ```
  </Step>

  <Step title="Add to Agent">
    ```typescript theme={null}
    // src/index.ts
    import { LuaAgent } from 'lua-cli';
    import { docsServer } from './mcp/docs';

    export const agent = new LuaAgent({
      name: 'my-agent',
      persona: '...',
      mcpServers: [docsServer]
    });
    ```
  </Step>

  <Step title="Compile">
    ```bash theme={null}
    lua compile
    # Server is registered, ID assigned
    ```
  </Step>

  <Step title="Push">
    ```bash theme={null}
    lua push mcp
    # or
    lua push all --force
    ```
  </Step>

  <Step title="Activate">
    ```bash theme={null}
    lua mcp activate docs-server
    # Tools are now available
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    lua mcp list
    # Shows docs-server as active
    ```
  </Step>
</Steps>

## Tips

<AccordionGroup>
  <Accordion title="Check status before activating">
    Use `lua mcp list` to see current status before making changes

    ```bash theme={null}
    lua mcp list
    # Shows which servers are active/inactive
    ```
  </Accordion>

  <Accordion title="Activate only what you need">
    Keep unused servers deactivated to reduce overhead

    ```bash theme={null}
    lua mcp activate docs-server    # When needed
    lua mcp deactivate docs-server  # When done
    ```
  </Accordion>

  <Accordion title="Use --force for automation">
    In CI/CD, use `lua push all --force` to avoid prompts

    ```bash theme={null}
    lua push all --force --auto-deploy
    ```
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={2}>
  <Card title="lua compile" href="/cli/skill-management#lua-compile" icon="gears">
    Compile and register MCP servers
  </Card>

  <Card title="lua push" href="/cli/skill-management#lua-push" icon="upload">
    Push MCP server configuration
  </Card>
</CardGroup>

## See Also

* [MCP Servers Overview](/overview/mcp-servers) - Conceptual introduction
* [LuaMCPServer API](/api/luamcpserver) - Complete API reference
* [Skill Management](/cli/skill-management) - Compile and push commands
* [Integrations Command](/cli/integrations-command) - Connect third-party accounts (auto-creates MCP servers)