Skip to content

08_MCP Servers

Jump to bottom
Umut Sevdi edited this page Oct 19, 2026 · 2 revisions

MCP Servers

Imza supports many MCP servers directly: GitHub, Linear, Slack, Notion, Stripe, Figma, and dozens more. Manage servers with /mcp at any time.

MCP servers modal

Adding a Server

In the Add Server section:

  1. Server: type to open the catalog dropdown and filter it. Entries marked (key) need an API key; (sign-in) entries authorize through your browser. Custom server… takes any https endpoint or a local command. Press Enter to pick.
  2. Transport (custom servers): a toggle between HTTP for a remote endpoint and stdio to launch a local program.
  3. API Key: shown only when the server needs one, masked in the list. The catalog says what to paste (for example, a GitHub personal access token).
  4. URL: custom HTTP servers only; the https address of the endpoint.
  5. Command / Args / Env / Work dir: custom stdio servers only. The command runs directly (no shell); args are space-separated, env is KEY=VALUE pairs, and the working directory is optional.
  6. Timeout: custom HTTP servers only, optional, in seconds.
  7. Label: optional, tells servers apart.
  8. Add: saves the server and connects it.

Catalog addresses resolve automatically, so they keep working across app updates. Custom servers accept ${NAME} or ${NAME:-fallback} environment references in the URL, token, headers, args, and env values; expansion happens when the connection is made.

Stdio servers run as local child processes and are stopped when you disconnect or remove them (stdin is closed, then the process is signaled). They are started only when you add them, never auto-started from project files.

Adding stdio server

Managing Servers

Saved servers are listed at the top:

Status Meaning
✓ Connected; the tool count is shown
⟳ Connecting
✗ Failed; the reason is on the row
○ Offline
Disabled Inactive; hidden from the agent

Buttons on the selected row: Connect/Disconnect, Disable/Enable, Remove. A failed connection retries on its own a few times before giving up; Connect retries sooner.

Keyboard: ↑↓ move between rows and the add form · Enter press the focused button · DEL remove the selected server (y confirms) · Esc close.

Sign-In Servers

(sign-in) entries authorize through the browser instead of an API key. Pick one, optionally give it a label, and press Sign in. Imza opens your browser to the service's consent page; once you approve, the row connects and shows its tool count. While the browser is open the row reads waiting for browser… and offers Cancel. A canceled or refused first sign-in leaves the row in the list; press Sign in on it to try again, or remove it.

Imza discovers the authorization server from the server itself (no endpoints to configure), registers a client automatically, and uses PKCE with a localhost callback. No password is involved.

If no browser can be opened (Imza running over SSH, for example), the wait times out after five minutes and the row shows the sign-in link to open by hand. The link's 127.0.0.1 callback port must still reach the machine running Imza (an SSH port forward of that port does it), so headless setups may prefer a (key) service instead.

Tokens live in your local configuration file under the server's oauth object. Unlike model API keys, they are not moved to the OS keychain. When an access token expires Imza renews it in the background; if renewal fails the row shows that sign-in is needed again; press Sign in to redo it.

How the Agent Uses Servers

The agent sees every server you configured, connected or not. When a task needs one, it loads that server's tool reference (names, descriptions, argument schemas) and calls the tools directly. With the matching servers connected you can ask it to check a Sentry issue, find the Linear issue for a bug, or pull up a library's current API.

An offline server connects when the agent loads it, once you say yes. --allow-mcp <id> says yes ahead of time for one run (see Headless mode). Loading a disabled or failed server does not ask; the agent just gets the reason.

When a server changes its tools, the inventory updates on its own; no reconnect needed.

A connected server's tools are available to the agent in every run, so Disable a server you do not want used. Disabling and removal take effect immediately.

In the Configuration File

Servers are stored under mcp_servers in your configuration file, one entry per id, keyed by the transport and address you chose. That is where you can see the stored token, set autoload for a server you always want connected, raise timeout_secs for a slow one (the /mcp form offers that field only for custom HTTP servers), or add headers. See Configuration for every key and its default.

Clone this wiki locally