# MCP Servers

[Docs](https://www.rightnowai.co/docs) / [RightNow Agent](https://www.rightnowai.co/docs/agent) / [MCP Servers](https://www.rightnowai.co/docs/mcp)

Updated 2026-10-11

> **Release status**
>
> RightNow Agent, the terminal coding agent, is paused. Its guides stay online as reference.

MCP (Model Context Protocol) servers add external tools to RightNow Agent. Define them under `[mcp_servers.NAME]` in `config.toml`.

## Transports

**MCP transports**

| Transport | Keys | Connection |
| --- | --- | --- |
| stdio | command, args, env | Spawns a local process and talks over stdin and stdout. |
| streamable HTTP | url, headers | Connects to a remote endpoint. |

The CLI accepts `http` and `sse`; both connect through the streamable HTTP client.

Template: replace the package, path, server URL, and environment-variable name before saving this in `config.toml`.

**TOML**

```toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "C:/work"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 6000
tool_timeouts = { slow_op = 120 }

[mcp_servers.remote-api]
url = "https://mcp.example.com/api"
bearer_token_env_var = "MCP_TOKEN"
```

`startup_timeout_sec` defaults to 30 seconds, `tool_timeout_sec` defaults to 6,000 seconds, and `tool_timeouts` sets per-tool overrides. On Windows, a bare `npx` resolves through `PATHEXT`, so no `cmd /c` wrapper is needed.

## Limits and environment expansion

- `MCP_TIMEOUT` is milliseconds, while `RIGHTNOW_MCP_STARTUP_TIMEOUT_SECS` is seconds. A server's `startup_timeout_sec` takes precedence over both.
- Large results are truncated at 20,000 bytes by default, with the full payload stored under the session's `mcp/` directory. `RIGHTNOW_MAX_MCP_OUTPUT_BYTES` takes precedence over `MAX_MCP_OUTPUT_BYTES`; `[mcp] max_output_bytes` sets it in `config.toml`.
- String values in `url`, `command`, `args`, `env`, and `headers` expand `${VAR}` and `${VAR:-default}` when configuration loads.

## User and project scope

**MCP configuration files**

| File | Scope |
| --- | --- |
| ~/.rightnow/config.toml | User, all projects. Lowest of the config.toml files; servers from other tools rank below it. |
| <repo>/.rightnow/config.toml | Repository. |
| <cwd>/.rightnow/config.toml | Current directory. Highest priority. |

Every directory from the repository root down to the current one is read. A project server replaces a same-named user server; fields do not merge.

> **Warning: Review server definitions**
>
> Servers run with your privileges and their own network and credential access. RightNow Agent 1.0.5 starts project servers from `.rightnow/config.toml`, `.mcp.json`, and `.cursor/mcp.json` without a folder-trust prompt; review a repository's files before running RightNow in it.

## Command-line management

The read-only list marks project-scoped and disabled entries.

**PowerShell**

```powershell
rightnow mcp list
```

Uppercase words are placeholders. The transport defaults to stdio. Add writes user scope unless `--scope project` is supplied.

**rightnow mcp commands**

| Action | Syntax |
| --- | --- |
| JSON list | `rightnow mcp list --json` |
| Add stdio | `rightnow mcp add NAME -e KEY=value -- COMMAND ARG` |
| Add remote | `rightnow mcp add --transport http NAME URL -H "NAME: VALUE"` |
| Enable or disable | `rightnow mcp enable NAME` / `rightnow mcp disable NAME` |
| Diagnose | `rightnow mcp doctor [NAME] [--json]` |
| Remove | `rightnow mcp remove NAME [--scope user\|project]` |

- Both `-e` and `-H` are repeatable. Environment and header values are stored verbatim, so reference secrets as `${VAR}` in project configuration.
- Names given to `add` may contain only letters, digits, hyphens, and underscores. `disable` writes the user `config.toml`; `enable` does too, and clears `enabled = false` in the nearest project file that defines the server. `remove` needs `--scope` when both scopes define the name.

## Authentication

- `bearer_token_env_var` names an environment variable whose value becomes the Bearer token.
- OAuth configuration can provide a client ID, a client-secret environment-variable name, and requested scopes. Use `oauth_client_id`, `oauth_client_secret_env_var`, and `oauth_scopes`.
- Authenticate a supported OAuth server from `/mcps`. Browser OAuth tokens are stored in `mcp_credentials.json` under the effective product home; on Unix the file uses owner-only permissions.

## Runtime controls and discovery

- `/mcps` opens the MCP Servers tab: `Space` toggles, `Enter` lists tools, `r` reloads, `i` authenticates, `a` adds, and `x` removes a local server.
- Tool names use `server__tool`, such as `github__create_issue`.
- `search_tool` finds tools across enabled servers; `use_tool` calls one by its full name.

## Servers from other tools

Also read in place, below `config.toml`:

**Servers from other tools**

| File | Turn off with |
| --- | --- |
| ~/.claude.json | `[compat.claude] mcps = false` |
| ~/.cursor/mcp.json, .cursor/mcp.json | `[compat.cursor] mcps = false` |
| .mcp.json | No switch; `/import-claude` (import or dismiss) stops it. Read from the current directory up to the repository root. |

- On a name conflict, `config.toml` wins, then Claude Code, Cursor, and `.mcp.json`. `rightnow inspect` shows each server's origin.
- `/import-claude` copies Claude Code servers into `config.toml`; afterwards `~/.claude.json` and `.mcp.json` are no longer read.
- Codex servers are not read in place. The Windows helper, run from the agent repository root, imports Claude Code or Codex definitions with `-WithMcp`; see the [migration guide](https://www.rightnowai.co/docs/migration).

Organization policy for MCP servers is covered in the [plugins guide](https://www.rightnowai.co/docs/plugins). If a server will not connect, run `rightnow mcp doctor`; a stdio server's stderr is saved to `logs/mcp/NAME.stderr.log` under the product home. Then continue with [troubleshooting](https://www.rightnowai.co/docs/troubleshooting).

## Previous

[Configuration Reference](https://www.rightnowai.co/docs/config-reference)

## Next

[Hooks](https://www.rightnowai.co/docs/hooks)