Connect MCP servers

Connect an MCP server to give Orek access to tools, prompts, or resources from another application. MCP stands for Model Context Protocol. Orek is the client: it starts or connects to the servers you configure and makes their tools available to the agent.

To add custom tools for your own services or commands, run your own MCP server. It must implement MCP and describe the tools and inputs you want Orek to use.

Start with one trusted server, verify its connection, and review the permissions before using its tools.

Before you begin

You need:

An installed Orek release and a configured model provider.
The server’s installation instructions, command or URL, and any credentials it requires.
An interactive Orek session (orek), a headless run (orek run), or an ACP editor session.

Supported connections

Orek supports these two MCP transports. Use the server publisher’s command or URL in place of the examples:

Transport	How it connects	Example command in your shell
stdio	Orek starts a local server process and exchanges messages through its standard input and output.	`orek mcp add example -- python my_server.py`
Streamable HTTP	Orek connects to a server at an `http://` or `https://` URL. The server may run locally or remotely.	`orek mcp add example --url https://mcp.example.com/mcp`

Streamable HTTP can stream responses using server-sent events (SSE). The older, separate HTTP+SSE transport is not supported, so use the server’s Streamable HTTP address.

Local servers can execute code on your machine. Review their source, publisher, and requested access before adding them.

Manage connections in Orek

If the server is already declared, open its picker:

In Orek · command

/mcp

Select a server to inspect its state or grant consent, sign in, enable/disable, or reload it (/mcp status prints a text summary). Granting consent to connect, signing in to the service, and approving individual tool calls are separate steps.

Ask a small question that needs the server, then inspect the tool result with /detail. An empty or failed result needs investigation; a server appearing in the list does not mean it connected.

Declaring a server

Add servers from your shell or config.toml (there is no TUI /mcp add command). After editing declarations, run /mcp reload or restart Orek.

For a Streamable HTTP server, choose the authentication method it supports:

In your shell

# OAuth: sign in after adding the server
orek mcp add example --url https://mcp.example.com/mcp --oauth

In your shell

# Bearer token: set MCP_API_TOKEN in the environment before starting Orek
orek mcp add example --url https://mcp.example.com/mcp --bearer-token-env MCP_API_TOKEN

orek mcp add writes to your user configuration by default; pass --scope project to write to .orek/config.toml. When both files declare the same [mcp.servers.<name>], project values override user values one setting at a time (for example enabled, allowed_tools, or timeouts). A server cannot have command in one file and url in the other. See the [mcp] configuration reference for all fields.

Enabled servers connect in the background after session startup, subject to consent and permission rules. Set mcp.enabled = false to disable MCP, or set a server’s enabled = false to disable that server. A failed connection does not end your Orek session.

Environment of stdio servers

Local MCP servers receive only part of your environment: the basic variables needed to start programs, such as PATH, HOME, OREK_HOME, and locale variables on Unix, or SystemRoot, ComSpec, TEMP, and PSModulePath on Windows. Provider API keys and other secrets are not passed on unless you declare them.

Declare additional variables in the server’s env map. In this example, replace the placeholder package with an actual server package. ${GITHUB_TOKEN} forwards that variable from Orek’s environment:

Configuration

[mcp.servers.github]
command = "npx"
args = ["-y", "@example/github-mcp"]
env = { "GITHUB_TOKEN" = "${GITHUB_TOKEN}" }

If a server works in your terminal but fails under Orek, check whether it depends on a variable you have not declared. The configuration reference describes the basic environment.

Repository configuration can request local processes or network connections. Orek therefore requires your consent before connecting a project-scope server. User-scope servers do not require this additional step.

In the TUI, first preview the server’s settings:

In Orek · command

/mcp consent <name>

Review the command and arguments. The preview masks environment and header values, the value after a credential flag such as --api-key, --token, or --client-secret, and credential NAME=value arguments. Flags that only mention credentials, such as --max-tokens, --auth-mode, or --auth-server, stay visible. URLs show their address, with sign-in details, query strings, and fragments masked. The preview grants nothing. To approve the declaration and connect:

In Orek · command

/mcp consent <name> confirm

Consent covers the exact declaration you reviewed and is saved in your user data folder, outside the repository. Any change to the declaration needs consent again. orek mcp reset-consent clears all saved consent.

orek mcp test <name> asks for the same consent when it tests a project-scope server.

OAuth

For an HTTP server configured with auth = "oauth", sign in before using it:

In your shell

orek mcp auth <name>

Or use /mcp auth <name> in Orek. Orek finds the server’s sign-in page, shows its URL, and opens your browser only if you confirm.

Connecting to a server does not start sign-in automatically; run orek mcp auth <name> (or /mcp auth <name>) and then reconnect. Orek refreshes expired access tokens automatically and prompts you to sign in again if the refresh token is rejected.

To sign out and delete the stored credentials:

In your shell

orek mcp logout <name>

orek mcp remove <name> keeps stored credentials unless you pass --delete-credentials.

Credential storage and recovery

OAuth tokens are stored locally in an encrypted file whose key is kept in your OS credential store, never in plain text. If that key is locked or missing while encrypted tokens remain on disk, unlock or restore it before signing in again.

Use orek mcp credentials orphans to list saved sign-ins for servers that may no longer be configured, and orek mcp credentials clean-orphans to revoke and delete them.

Diagnosing a server

Verify the declaration and connection before asking the agent to use a tool:

In your shell

# Inspect scope, consent, and credential state without connecting
orek mcp list

In your shell

# Connect once and report server information, protocol version, and tools
orek mcp test <name>

orek mcp test agrees on an MCP protocol version with the server (2026-07-28 or 2025-11-25) and lists its tools. Some servers on the older version do not answer Orek’s first request, and Orek waits 10 seconds before retrying the older way.

In Orek, /mcp status shows connected servers as ready. Orek refreshes their tools, prompts, and resources when the server reports changes. Tools appear as mcp__{server}__{tool}, cut to 64 characters.

Symptom	What to check
Awaiting consent	Preview and confirm the project declaration.
Authentication required or expired	Run `orek mcp auth <name>`, then reconnect.
Works in a terminal but fails in Orek	Check the declared executable, arguments, and environment.
Tools are missing	Check `allowed_tools`, permission rules, and whether this session supports MCP. For a subagent, check its profile’s tool list.
An older server times out on its first connection attempt	Raise its `startup_timeout_secs` above 10 seconds. The retry connects either way.
A server shows `timed out` after retrying	It did not connect and list its tools within `startup_timeout_secs`. Raise it, then reconnect the server.
A `timed out` detail reads `tools/list timed out after 15s`	Each page of the server’s first tool list must arrive within 15 seconds, whatever `startup_timeout_secs` is. Make the server list its tools faster, then reconnect it.
A long tool call times out	Raise `tool_timeout_secs`, or have the server report progress.
`tool re-list failed` after a reload or server change	The server stayed connected but could not list its tools. Orek keeps the tools it last listed. Check the server’s log, then reload it.
Connection failed	Inspect the server report and `orek log`, then reconnect after correcting the cause.

A tool call waits up to tool_timeout_secs for a result. Each progress report from the server restarts that wait, up to ten times tool_timeout_secs in total. A local server’s error output goes to Orek’s log. With soft_fail = true, a server that fails to start is logged as a warning rather than an error.

In the TUI

Use /mcp to open the server picker, or use a specific command:

Command	Result
`/mcp status`	Show connection states and available tools, prompts, and resources.
`/mcp consent <name>`	Preview a project declaration; add `confirm` to grant consent.
`/mcp enable <name>` or `/mcp disable <name>`	Enable or disable a server for this session.
`/mcp reload [name]`	Refresh the server’s tools, prompts, and resources; a server whose retries ran out reconnects.
`/mcp resources [name]`	Show the cached resource list.
`/mcp auth <name>`	Sign in to an OAuth HTTP server.
`/mcp logout <name>`	Revoke and remove stored OAuth credentials for a server.

The panel updates as servers connect, reload, sign in, or fail. If a reload cannot list a server’s tools, a banner shows why and the server keeps its previous tools. Each row shows the server’s name, state, user or project origin, transport, and number of tools, prompts, and resources. The selected server expands to show its masked address, timeouts, full error message, and available actions.

Key	Action
Up/Down or j/k, Page Up/Page Down	Navigate or page through servers.
`/`	Enter filter mode (`Enter` or `Esc` returns to navigation).
Esc, q, or Ctrl+C	Clear the filter (`Esc`), or close the control panel.
Enter / i	Open the 4-tab server inspector (`1`–`4` or `Tab` switches `Tools`, `Prompts`, `Resources`, and `Config & Status`).
e / d (or Ctrl+E / Ctrl+D)	Enable or disable a server for this session (disabling also cancels an in-flight connection or OAuth attempt, and stops a failed server from retrying). Disable needs a second press.
R / Ctrl+X	Reconnect a server. Needs a second press.
r / Ctrl+R	Refresh tools, prompts, and resources on a ready server.
a / o (or Ctrl+A / Ctrl+O)	Start OAuth sign-in (including for an expired token) or revoke stored OAuth credentials. Both need a second press.
Ctrl+L	Open the selected server’s inspector on the `Resources` tab.

On an awaiting-consent row, press c to preview the masked declaration inline, then press c again to grant consent and connect.

Disabling, reconnecting, signing in, and logging out drop the server’s connection or delete its stored credentials, so none of them runs on the first press. The first press shows a warning that names the action and the server; press the same key again to run it. Esc, moving the selection, or any other key cancels it, and holding a key down never counts as the second press.

Prompts, resources, and input requests

Server prompts appear as /mcp__{server}__{prompt} slash commands. Running one sends the server’s prompt text as your message. The agent reads resources with the read_mcp_resource tool.

During a tool call, a server can request input (elicitation) in Orek’s question box, or show an http/https URL that opens only if you confirm. Headless runs and ACP sessions decline elicitation.

Security posture

Consent to connect a server and permission to execute its tools are separate checks:

MCP tools ask for approval by default. A server marking a tool as read-only does not change its approval, or let an interrupted workflow rerun the call automatically.
[permissions.mcp_server_rules] can allow, ask, or deny by server, and the first matching rule wins. A server denied in the default, auto_review and yolo modes never starts, its tools stay hidden, and enabling, reconnecting, consenting to or signing in to it is refused, including by orek mcp test and orek mcp auth. You can still sign it out to remove its stored credentials. A rule that applies in only some of those modes leaves the server running and blocks its tools in those modes.
A server’s allowed_tools setting limits which of its tools Orek offers.
Orek treats server tool descriptions as untrusted. It removes control characters, collapses whitespace, and limits each description to 2 KB.
mcp.tool_output_max_chars limits tool output to 100,000 characters by default. Images and other binary output are saved as temporary files, and the output shows their paths.
orek config show, orek doctor, and orek mcp list hide environment and header values. orek doctor and orek mcp list show only the scheme, host, and port of server URLs; orek config show hides only a user name and password written into a URL.
Subagents see the session’s MCP tools unless their profile’s allowed_tools omits them, and their calls follow the same permission rules and approval prompts. See Subagents.

Current limits

MCP tools are available in TUI, orek run, and ACP sessions (unless --no-tools or mcp.enabled = false is set).
Orek supports elicitation during tool calls, but does not support MCP sampling, roots, logging, tasks, or input prompts during resource/prompt reads.
A connected editor can pass its own stdio or Streamable HTTP servers to a session. A server with the same name as one you configured uses the editor’s connection but keeps your enabled, allowed_tools, timeout, and [permissions.mcp_server_rules] settings. Your saved credentials are never used for it, and editor sessions never start OAuth sign-in. See IDE integration.

For configuration fields, continue to the MCP reference. For a tool’s permission behavior, see Permissions and security.

Before you begin

Supported connections

Manage connections in Orek

Declaring a server

Environment of stdio servers

Consent for project-scope servers

OAuth

Credential storage and recovery

Diagnosing a server

In the TUI

Prompts, resources, and input requests

Security posture

Current limits