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

# MCP Servers

> Store MCP server entries in the Desktop app (not launched yet)

The Desktop app's MCP panel stores server entries for a future release. The engine does not launch them yet, so the model cannot use them.

<Warning>
  **Stored for a future release.** The engine does not launch these servers yet, so the model cannot use them. For MCP that reaches the agent today, use the SDK path in [MCP Overview](/docs/features/mcp).
</Warning>

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Panel[🖥️ Manage MCP Panel] --> Store[(📁 mcp.json)]
    Store -.->|not wired yet| Agent[🤖 Agent]

    classDef ui fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef store fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef pending fill:#8B0000,stroke:#7C90A0,color:#fff

    class Panel ui
    class Store store
    class Agent pending
```

## Quick Start

<Steps>
  <Step title="Open the Manage MCP panel">
    Find the Manage MCP panel in the app.
  </Step>

  <Step title="Store a server entry">
    Enter a **name**, **command**, and **args**, then save. This writes the entry to `mcp.json` — it does not launch anything.
  </Step>

  <Step title="Enable, disable, or remove a stored entry">
    The toggle only flips the `enabled` flag in storage. Removing deletes the entry. Nothing else changes today — the agent still uses only built-in tools.
  </Step>
</Steps>

***

## How It Works

The app stores servers through a single endpoint (`POST /mcp`) with an `action` of `add`, `remove`, or `toggle`, and lists them with `GET /mcp`. Storage is the only thing that happens — no process is launched.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Add[➕ add] --> Store[(📁 mcp.json)]
    Toggle[🔀 toggle] --> Store
    Remove[➖ remove] --> Store
    Store --> List[📋 GET /mcp]

    classDef action fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef store fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef list fill:#10B981,stroke:#7C90A0,color:#fff

    class Add,Toggle,Remove action
    class Store store
    class List list
```

These fields are recorded so a future release can pick them up:

| Field     | Type     | Notes                                                       |
| --------- | -------- | ----------------------------------------------------------- |
| `name`    | `string` | Required; adding an existing name replaces it               |
| `command` | `string` | The executable a future release will launch                 |
| `args`    | `array`  | Arguments a future release will pass to the command         |
| `enabled` | `bool`   | Defaults to `true` on add; only flips the stored flag today |

<Note>
  Adding a server with a name that already exists replaces the previous entry rather than duplicating it.
</Note>

### Add errors

The **Add** button refuses bad input and keeps the panel open so you can correct the entry.

* **Blank name.** The **Add** button is refused with an in-app dialog reading **"A name is required."** — nothing is written to `mcp.json` and the panel stays open.
* **Engine rejection.** If the engine refuses the add (for example an invalid command), an in-app dialog surfaces the engine's error message and the panel stays open so you can correct the entry.

The MCP settings overlay dims a toast beneath its scrim, so errors from this panel surface through the in-app dialog instead — that dialog paints above the scrim and stays readable. If neither the dialog nor the write happens on an older build, see [Troubleshooting](/docs/features/desktop/troubleshooting).

***

## Today vs Future

The panel stores data now; a future release wires it to the agent.

| Today                                            | Future release                            |
| ------------------------------------------------ | ----------------------------------------- |
| Store an entry (name / command / args / enabled) | Same storage picked up by the engine      |
| Entries survive restarts                         | Enabled entries launched over stdio       |
| The agent uses only built-in tools               | The agent sees tools from enabled servers |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use the SDK for MCP that works today">
    The Desktop panel is storage-only. To give an agent real MCP tools now, use the SDK path in [MCP Overview](/docs/features/mcp).
  </Accordion>

  <Accordion title="Name servers clearly">
    The name is the key. A clear, unique name prevents an accidental replace when you add a new entry.
  </Accordion>

  <Accordion title="Toggle instead of removing">
    Disable a stored entry you may want back rather than removing it — the entry and its args are preserved for the future release.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="MCP Overview" icon="plug" href="/docs/features/mcp">
    The only path that gives MCP tools to the agent today
  </Card>

  <Card title="Settings Reference" icon="sliders" href="/docs/features/desktop/settings">
    Other Desktop app configuration
  </Card>
</CardGroup>