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

# Use Lua with Claude, Cursor & AI IDEs

> Connect Lua's documentation to your AI coding assistant in minutes via MCP

## Overview

Lua publishes an MCP (Model Context Protocol) server at `https://docs.heylua.ai/mcp`. Add it to any MCP-compatible AI tool — Claude Desktop, Cursor, Windsurf, and others — and your assistant gains direct, always-up-to-date access to the full Lua CLI documentation.

Once connected, you can ask questions like *"How do I create a scheduled job?"* or *"Show me the LuaJob API"* and get answers grounded in the real docs, not stale training data.

<Note>
  The MCP server is hosted and maintained by Mintlify. It auto-updates whenever the Lua docs are published, so it is always current.
</Note>

## What you get

Two tools become available inside your AI tool the moment it connects:

| Tool                            | What it does                                                                                                                                                                             |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_lua_cli`                | Semantic search across all Lua CLI documentation                                                                                                                                         |
| `query_docs_filesystem_lua_cli` | Run read-only shell-like queries (`head`, `cat`, `rg`, `ls`, `tree`, `grep`, `find`, `jq`, ...) against a virtualized, in-memory filesystem of every documentation page and OpenAPI spec |

Your AI assistant will use these automatically when you ask Lua-related questions: `search_lua_cli` for broad/conceptual queries ("how do I authenticate?") and `query_docs_filesystem_lua_cli` to read the full content of a specific page by path (e.g. `head -200 /cli/debugging.mdx`) or to do exact keyword/regex matches across the docs.

***

## Claude Desktop

<Steps>
  <Step title="Open your Claude Desktop config">
    On **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

    On **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

    Create the file if it does not exist.
  </Step>

  <Step title="Add the Lua MCP server">
    ```json theme={null}
    {
      "mcpServers": {
        "lua-docs": {
          "type": "http",
          "url": "https://docs.heylua.ai/mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Claude Desktop">
    Quit and reopen the app. You should see the Lua tools listed in the MCP tools panel.
  </Step>
</Steps>

***

## Cursor

<Steps>
  <Step title="Create or open your MCP config">
    **Project-level** (only active in this project):

    ```
    .cursor/mcp.json
    ```

    **Global** (active in all projects):

    ```
    ~/.cursor/mcp.json
    ```
  </Step>

  <Step title="Add the Lua MCP server">
    ```json theme={null}
    {
      "mcpServers": {
        "lua-docs": {
          "url": "https://docs.heylua.ai/mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Reload Cursor">
    Open the Command Palette (`Cmd/Ctrl + Shift + P`) and run **Reload Window**, or restart Cursor. The Lua tools will appear in the MCP section of your Cursor settings.
  </Step>
</Steps>

***

## Windsurf

<Steps>
  <Step title="Open your Windsurf MCP config">
    ```
    ~/.codeium/windsurf/mcp_config.json
    ```
  </Step>

  <Step title="Add the Lua MCP server">
    ```json theme={null}
    {
      "mcpServers": {
        "lua-docs": {
          "serverUrl": "https://docs.heylua.ai/mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Windsurf">
    Restart the editor to pick up the new server.
  </Step>
</Steps>

***

## Other tools (mcp-remote fallback)

For AI tools that only support the **stdio** transport (rather than HTTP), use the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge:

```json theme={null}
{
  "mcpServers": {
    "lua-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://docs.heylua.ai/mcp"]
    }
  }
}
```

This works with any tool that accepts an `npx`-style stdio MCP server definition.

***

## What to ask

Once connected, your AI assistant can answer questions like:

* *"How do I define a LuaJob with a cron schedule?"*
* *"What flags does `lua jobs deploy` accept?"*
* *"Show me the full Jobs API reference."*
* *"How do I test a webhook locally?"*
* *"What's the difference between a preprocessor and a postprocessor?"*

The assistant will call `search_lua_cli` to find the relevant pages and `query_docs_filesystem_lua_cli` (with commands like `head -200 /cli/logs-command.mdx` or `rg -il "agent_error" /`) to pull their full content or do precise keyword matches — so answers come from the actual documentation, not guesswork.

***

## Related

<CardGroup cols={2}>
  <Card title="AI Agent Building Guide" icon="wand-magic-sparkles" href="/ai-guide">
    Complete workflow for building Lua agents with Cursor, Windsurf, or GitHub Copilot
  </Card>

  <Card title="MCP Servers Overview" icon="plug" href="/overview/mcp-servers">
    Connect external MCP servers to your Lua agent
  </Card>

  <Card title="CLI Overview" icon="terminal" href="/cli/overview">
    All available Lua CLI commands
  </Card>

  <Card title="LuaMCPServer API" icon="book" href="/api/luamcpserver">
    Connect external tools to your agent via MCP
  </Card>
</CardGroup>