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

# MCP Servers: Give Luminy Access to External Services

> Connect Model Context Protocol (MCP) servers to Luminy to add external tools like web search, databases, cloud APIs, and custom integrations.

Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools provided by third-party servers. By connecting an MCP server to Luminy, you instantly give the agent new capabilities — web search, GitHub access, database queries, cloud provider APIs, or any custom tool you build — without any changes to Luminy itself. Once a server is connected, its tools appear in the agent's palette automatically and are used just like built-in tools.

## Supported transports

Luminy supports two ways to connect an MCP server:

<CardGroup cols={2}>
  <Card title="stdio" icon="terminal">
    Luminy spawns a local process on your machine and communicates over stdin/stdout. Ideal for lightweight tools distributed as npm packages or executables.
  </Card>

  <Card title="HTTP / SSE" icon="globe">
    Luminy connects to a running server over HTTP using Server-Sent Events. Use this for hosted or remote MCP servers.
  </Card>
</CardGroup>

## Adding an MCP server

<Steps>
  <Step title="Open Settings → MCP">
    Click the settings icon in the sidebar, then select the **MCP** tab.
  </Step>

  <Step title="Click Add Server">
    Press the **+ Add Server** button to open the connection dialog.
  </Step>

  <Step title="Choose a transport">
    Select **stdio** for a local command or **HTTP** for a remote server URL.
  </Step>

  <Step title="Enter the connection details">
    **For stdio:** Enter the executable in the **Command** field and any arguments in the **Args** field (one per line). For example, to add the Brave Search server:

    * **Command:** `npx`
    * **Args:** `-y` then `@modelcontextprotocol/server-brave-search` (one per line)

    You can also set **Environment** variables as `KEY=VALUE` pairs (one per line) if the server requires them.

    **For HTTP:** Enter the server URL in the **URL** field, for example:

    ```text theme={null}
    https://mcp.example.com/mcp
    ```

    When you type an HTTP URL, Luminy automatically probes the server and fills in the name if it exposes a discovery endpoint.
  </Step>

  <Step title="Name the server">
    Give the server a human-readable name. Luminy may pre-fill this from the server's discovery metadata.
  </Step>

  <Step title="Save">
    Click **Add**. Luminy connects to the server immediately and lists the tools it exposes. If the connection succeeds, the server's tools are available to the agent right away.
  </Step>
</Steps>

## OAuth authentication

Some MCP servers — typically hosted services — require OAuth authorization before they will accept requests. Luminy handles the full OAuth 2.0 PKCE flow for you:

1. Luminy detects the OAuth requirement automatically when you enter the server URL.
2. A browser window opens for you to sign in and grant access.
3. After you authorize, Luminy receives the tokens and stores them securely. The server is added and connected.

<Note>
  If a server requires static client registration (pre-issued client credentials not obtained via dynamic registration), it is not currently supported. Luminy only supports servers that implement dynamic client registration.
</Note>

## Example servers to try

These are all **stdio** servers. For each one, set **Command** to `npx` and enter the remaining tokens as separate lines in **Args**.

| Server       | Args (one per line)                                               | What it adds                             |
| ------------ | ----------------------------------------------------------------- | ---------------------------------------- |
| Brave Search | `-y` / `@modelcontextprotocol/server-brave-search`                | Web search results                       |
| Filesystem   | `-y` / `@modelcontextprotocol/server-filesystem` / `/path/to/dir` | Scoped read/write access to a directory  |
| GitHub       | `-y` / `@modelcontextprotocol/server-github`                      | Repository access, issues, pull requests |

Set any required API keys (such as `BRAVE_API_KEY=your_key`) in the **Environment** field.

<Tip>
  You can also import MCP server configs in bulk by pasting a JSON object in the standard `mcpServers` format. Luminy parses the object, adds each entry, and attempts to connect them all at once.
</Tip>

## Managing servers

All connected servers are listed on the **Settings → MCP** page. From there you can:

* **Enable / disable** a server with the toggle. Disabling a server disconnects it without deleting its configuration.
* **Test** the connection to refresh the tool list and verify the server is reachable.
* **Remove** a server to disconnect it and delete its configuration permanently.

## Important notes

<Warning>
  **Only connect MCP servers you trust.** An MCP server's tools run with the same permissions as any other agent tool. A malicious server could instruct the agent to read files, run commands, or make network requests on your behalf. Treat MCP servers the same way you would treat any third-party CLI tool you install.
</Warning>

<Note>
  **stdio servers run as child processes on your machine.** They inherit your user environment and have access to your filesystem paths. **HTTP servers** communicate over the network; be mindful of what data you send to remote endpoints.
</Note>