---
name: mcp
description: Install, configure, login/logout, list/get/remove, or troubleshoot MCP servers. Read this doc before doing anything with an MCP server.
---

# MCP Servers

## Primary Commands

Use the CLI for MCP management:

```bash
shortcut mcp list [--json]
shortcut mcp get <name> [--json]
shortcut mcp add <name> --url <url> [--no-login] [--force]
shortcut mcp remove <name>
shortcut mcp login <name>
shortcut mcp logout <name>
```

In a source checkout before the package is installed, run the same command through the source entrypoint:

```bash
cd shortcutXL/runtime && pnpm exec tsx src/cli.ts mcp <subcommand>
```

After a successful add or manual config change, tell the user to restart ShortcutXL before using the newly installed tools.

## Install Rules

Choose one path:

1. Hosted URL (`https://.../mcp`): use `shortcut mcp add <name> --url <url>`. Do not hand-edit `mcp.json` for normal hosted URL installs.
2. Local stdio package or executable: edit `~/.shortcut/agent/mcp.json` with `command` and `args`.
3. Hosted server with static headers or API keys: edit `~/.shortcut/agent/mcp.json` with `headers` or `connection` after the user or provider docs give the exact header names.
4. Advanced fallback: edit JSON directly only when the installer is unavailable, failed, or the provider requires unsupported fields.

Do not substitute legacy `/sse` URLs for hosted installs. Do not use `/connect` for normal hosted OAuth; `/connect` is for local env vars or intentional static-header secrets.

## Hosted URL Install

Use this for URLs like `https://example.com/mcp`:

```bash
shortcut mcp add notion --url https://mcp.notion.com/mcp
```

The installer:

- Writes `~/.shortcut/agent/mcp.json`.
- Stores hosted servers as `{ "transport": "streamable_http", "url": "..." }`.
- Detects hosted OAuth support.
- Starts browser login automatically when OAuth is required.
- Stores OAuth credentials in ShortcutXL auth storage.
- Rejects duplicate server names unless `--force` is used.

For hosted OAuth login/logout after install, use:

```bash
shortcut mcp login <name>
shortcut mcp logout <name>
```

## Local Stdio Install

Use local stdio only when the server README gives a local package or executable.

1. Check the README for `command`, `args`, and required env vars.
2. If credentials are needed, run `/connect` and create fields whose names exactly match those env vars.
3. Add the server to `~/.shortcut/agent/mcp.json`.
4. Tell the user to restart ShortcutXL.

Example:

```json
{
  "mcpServers": {
    "github": {
      "command": "pnpm",
      "args": ["dlx", "@modelcontextprotocol/server-github"],
      "connection": "github",
      "startupTimeoutMs": 30000,
      "toolCallTimeoutMs": 600000,
      "resetToolCallTimeoutOnProgress": true
    }
  }
}
```

For local package installs, use `pnpm dlx` so package execution goes through pnpm policy instead of prompting interactively.

`connection` names a `/connect` secret bundle. Each `/connect` field is injected as an env var into the local MCP process, so field names must exactly match the env vars the server expects.

## Manual Hosted Config

Do not start here for a normal hosted URL. Start with `shortcut mcp add`.

Manual hosted config is only for static auth, advanced provider overrides, or installer fallback.

```json
{
  "mcpServers": {
    "vendor": {
      "transport": "streamable_http",
      "url": "https://vendor.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${VENDOR_TOKEN}"
      },
      "connection": "vendor"
    }
  }
}
```

## User-Facing TUI

`/mcp` is primarily for user inspection and diagnostics:

- inspect loaded servers, tools, and status
- open MCP settings
- confirm whether restarting ShortcutXL picked up a config change

For user-facing OAuth fallback, `/login` -> `MCP: <server>` is valid. Agent-run login/logout should use `shortcut mcp login <name>` and `shortcut mcp logout <name>`.

## Troubleshooting

Inspect raw state in this order:

1. Run `shortcut mcp list --json` and `shortcut mcp get <name> --json`.
2. Read `~/.shortcut/agent/mcp.json`.
3. Read recent MCP lines in `~/.shortcut/agent/logs/agent.log`.
4. Redact secrets before showing config or log excerpts to the user.

| Problem                                           | Likely cause                                           | Fix                                                              |
| ------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------- |
| Server not listed in `/mcp`                       | Config not loaded                                      | Tell the user to restart ShortcutXL                              |
| Hosted URL was configured with `command` / `args` | Hosted server was treated as stdio                     | Replace with `shortcut mcp add <name> --url <url>`               |
| `needs login` or `login required`                 | Hosted OAuth server is installed but not authenticated | Use `shortcut mcp login <server>` or `/login` -> `MCP: <server>` |
| Hosted server says `authorization_required`       | Missing OAuth login or static headers                  | For OAuth use login; for static auth configure `headers`         |
| Local server has no credentials                   | Missing `/connect` connection or wrong field names     | Create the connection and match README env var names exactly     |
| `did not respond within 30s`                      | Local server hung during startup                       | Test the command manually and check the `pnpm dlx` invocation    |
| Tool call timed out                               | Long-running MCP operation                             | Increase `toolCallTimeoutMs`                                     |
| Config parse error on Windows                     | Unescaped backslashes                                  | Use forward slashes in JSON paths                                |
