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

# Adding a stdio MCP Server

> Connect a local command-line MCP server to MIRA.

A **stdio** MCP server runs as a subprocess on your machine. MIRA launches it with a shell command and communicates through stdin/stdout. No network port is required.

## Prerequisites

* The MCP server binary or script must be installed and executable on your PATH.
* Verify it works by running `npx -y @modelcontextprotocol/inspector <your-command>` in a terminal.

## Add the server in MIRA

<Steps>
  <Step title="Open Settings">
    Press ⌘, and navigate to **MCP Tools**.
  </Step>

  <Step title="Click Add Server">
    Click the **+ Add Server** button.
  </Step>

  <Step title="Select transport">
    Choose **stdio** from the Transport dropdown.
  </Step>

  <Step title="Enter the command">
    Type the shell command that launches your MCP server.

    Examples:

    | Server               | Command                                                       |
    | -------------------- | ------------------------------------------------------------- |
    | Filesystem tools     | `npx -y @modelcontextprotocol/server-filesystem /path/to/dir` |
    | GitHub tools         | `npx -y @modelcontextprotocol/server-github`                  |
    | Custom Python script | `python /path/to/my_mcp_server.py`                            |
  </Step>

  <Step title="Set environment variables (optional)">
    Click **Add Env Var** to inject environment variables such as API keys into the subprocess.

    <Warning>
      Environment variables entered here are stored in the OS keychain, not in plain text. They are not included in exports.
    </Warning>
  </Step>

  <Step title="Give the server a name">
    Enter a short name (e.g. `filesystem`). This name becomes the tool namespace prefix.
  </Step>

  <Step title="Set scope">
    Choose **Session** (active only in the current chat) or **Global** (always available).
    See [Session vs Global](./session-vs-global) for details.
  </Step>

  <Step title="Save and connect">
    Click **Save**. MIRA launches the subprocess and calls `list_tools`. Available tools appear
    in the server card within a few seconds.
  </Step>
</Steps>

## Verifying the connection

After saving, the server card shows:

* 🟢 **Connected** — tools discovered successfully
* 🔴 **Error** — command failed; hover for the error message

Click the server card to expand and see the full list of discovered tools.

## Troubleshooting

| Symptom                         | Fix                                                                             |
| ------------------------------- | ------------------------------------------------------------------------------- |
| Server shows Error immediately  | Run the command in a terminal to see the raw error output                       |
| Tools not appearing             | Ensure the server outputs valid MCP JSON-RPC on stdout (no extra debug logging) |
| Environment variable not passed | Verify the variable name exactly matches what the server expects                |
| Server disconnects mid-session  | Check if the subprocess crashes; add `--verbose` to the command if available    |

<Note>Edit this page — [Open a pull request](https://github.com/satyendra2013/mira-app/edit/main/docs/features/mcp-tools/adding-stdio-server.mdx)</Note>