> ## 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 servers > External Model Context Protocol servers whose tools the agent can call, attached with LuaMCPServer An MCP server is a remote service that exposes tools over the Model Context Protocol. Attaching one to an [agent](/concepts/agents) gives the model every tool the server advertises, discovered at runtime, with no tool code in your project. It exists so a vendor's or your own MCP server can serve the agent without you wrapping each of its operations in a [tool](/concepts/skills-and-tools). ## How an MCP server is attached You declare the server with `LuaMCPServer` and register it on the agent's `mcpServers`: ```ts src/mcp/docs.mcp.ts theme={null} import { LuaMCPServer, env } from 'lua-cli'; export default new LuaMCPServer({ name: 'docs', transport: 'streamable-http', url: 'https://mcp.example.com/mcp', headers: () => ({ Authorization: `Bearer ${env('DOCS_MCP_TOKEN')}` }), timeout: 60000, }); ``` Two transports are supported: `streamable-http`, the current MCP standard with a single endpoint, and `sse` for older servers. A `stdio` transport (a local process started with `npx` or `node`) is not supported, and the constructor throws if you pass it. `url` and `headers` accept a function as well as a value; a function runs on the platform when the server's configuration is built (its result is cached for a few minutes), so `env()` inside it reads the agent's environment and the secret never lands in configuration. `timeout` is in milliseconds; leave it unset and the platform's own 60-second client timeout applies. The lifecycle differs from versioned primitives. `lua push mcp` registers the server on the platform by name, or updates the record with the same name; there are no versions, and nothing changes for end users yet. `lua mcp activate ` activates it: the agent connects, lists the server's tools, and the model can call them on its next turn, in production. `lua mcp deactivate ` removes the tools again, and `lua mcp delete ` removes the record. `lua mcp list` shows every server and its state. Because activation changes the live agent, treat it like a deploy; `lua push mcp --auto-deploy` pushes and activates in one step. Nothing in the CLI lists the tools a server contributed. `lua mcp list` prints each server's name, transport, URL, ID, and whether it is active; the platform discovers the tools when a conversation needs them, server by server, each with a time budget. A server that fails discovery contributes no tools for that turn and the rest of the agent carries on, so a successful activation proves the record, not the connection. To confirm the tools are there before end users hit them, ask the agent in `lua chat` for something only that server can do, then read `lua logs --type mcp`: every call the model makes is logged with the server name and the tool name. Servers provided by [integrations](/concepts/integrations) are managed separately. Connecting a Unified.to integration provisions an MCP server for that connection; you list, activate, and deactivate those with `lua integrations mcp list|activate|deactivate --connection `, and you should not hand-write a `LuaMCPServer` for a SaaS the catalog covers. The docs MCP you connect to Cursor or Claude Code is a different thing: it serves this documentation to the coding tool while you build and has nothing to do with your agent's runtime. See [Docs MCP](/build-with-ai/docs-mcp). ## MCP servers and skills A [skill](/concepts/skills-and-tools) is tools you write, versioned and deployed with your agent, with a `context` that tells the model when to use them. An MCP server is tools someone else wrote, discovered at runtime, with descriptions you do not control. Use an MCP server when the operations already exist behind MCP; use a skill when you need custom logic, your own descriptions, or a tool the model should see only under a condition. An integration is a third option: a connection to a known SaaS that provisions its MCP server for you and adds events and raw API access. ## When to use it * A vendor or an internal team ships an MCP server for the system you need: attach it. * The SaaS is listed by `lua integrations available`: connect the integration instead; it provisions the MCP server and handles authentication. * You need one operation with your own validation or description: write a tool. * The server runs only as a local process: not supported; host it behind HTTP first. ## Limits | Item | Value | | ---------- | ---------------------------------------------------------------------- | | Transports | `streamable-http`, `sse` | | `timeout` | Milliseconds; the platform's client timeout of 60 s applies when unset | | Versioning | None; `lua push mcp` updates the record by name | ## Next steps Attach, push, activate, and verify the tools in a chat. Every configuration field. List, activate, deactivate, and delete servers. Integrations that provision their own MCP servers.