MCP integrations

Model Context Protocol (MCP) servers extend the agent's tool surface. A server publishes a set of tools; the agent can call those tools during a run alongside its built-in retrieval, edit, and terminal tools. Vortex ships no servers of its own — you add the ones you want.

What a server adds

An MCP server is a local process or a remote endpoint that describes tools over the Model Context Protocol. Once connected, its tools are available to the agent in every mode. Typical servers wrap a database, an issue tracker, a documentation source, or an internal API.

Two transports are supported:

• stdio — Vortex launches a local command and talks to it over standard input and output.
• HTTP — Vortex connects to a remote URL and, when the server requires it, signs in through your browser.

Where the configuration lives

Server definitions live in one file:

Set VORTEX_MCP_CONFIG when you want a separate config for a machine, a test run, or a script. The value replaces the default path; nothing else changes.

The usual way to edit the file is Settings → Integrations, which writes the same JSON and validates it before saving.

Per-workspace servers

A server can be scoped to a single workspace, so one repository can have a different tool surface than another. That matters when a repo needs a project-specific server and you do not want it active everywhere.

For each server you can:

• Copy the configuration to another workspace.
• Move it from one workspace to another.
• Reset it back to the user-level definition.

Stored secrets are never displayed. When you copy or move a server, Vortex carries the secret reference across without revealing the value in the dialog, the transcript, or the log.

A worked example

The file is a JSON object keyed by server name. This example defines one stdio server and one remote HTTP server:

{
  "servers": {
    "postgres-readonly": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@example/mcp-postgres"],
      "env": { "DATABASE_URL": "${PG_URL}" }
    },
    "sentry": {
      "transport": "http",
      "url": "https://mcp.example.com/sentry",
      "read_only": true
    }
  }
}

Keep secrets out of this file where you can. For a stdio server, prefer a value the command reads from your environment; for an HTTP server that needs a token, let the OAuth flow store it instead of pasting it into the config.

Remote servers and OAuth

Remote HTTP servers sign in through your system browser. Vortex opens the authorization page, you approve access, and the app stores the resulting tokens separately from the server config:

Tokens are written with mode 0600 and are never rendered in the UI. Do not paste a token into a prompt, an issue, or a log line — treat it the way you treat an API key. If a token leaks, revoke it at the provider and reconnect the server.

Seeing which server acted

Tools keep their own names. When the agent calls one, the transcript shows the tool name and the server it came from, so you can tell a built-in edit from a third-party query. Use that to audit what a server actually did during a run.

Troubleshooting

The server does not start. Run the command by hand, outside Vortex, in the same environment. If it fails there, the problem is the command, the package, or a missing environment variable, not the app.

Authentication expired. Reconnect the server from Settings → Integrations to run the browser flow again. An expired token surfaces as an auth error rather than a silent failure.

The server is slow to start. A stdio server that installs a package on first run delays the first call. Warm it up once, or point command at an already-installed binary.

The server exposes a dangerous tool. Review what a server publishes before you enable it. Destructive tools (drop, delete, deploy) are only as safe as the credentials you hand the server. Give it a read-only key where the server supports one.

Related

• Models and keys — how provider keys are stored, and why secrets stay out of the repo.
• Headless CLI — running the same workspace without the GUI.
• Quickstart — the understand, plan, implement, verify loop.

---

Vortex is in a closed beta on macOS. Add your email to the waitlist to get an invite.