How to install an MCP server

Digitorn treats MCP servers like apps in an app store: the Hub curates a catalog of well-known servers, you click Install, fill any personal credential the server needs, and your agents can reference it from any app.yaml by short name. Power users can also declare arbitrary servers inline in YAML.

This page covers both paths end-to-end.

Path 1 - Install from the Hub Catalog

This is the right path for 95% of cases. It's the "App Store" experience: pre-configured by Digitorn, only personal credentials asked.

From the dashboard

1. Open the Digitorn desktop dashboard → Admin → MCP Servers.
2. Stay on the Catalog tab. The list of supported servers is the curated catalog served by the Hub. Each card shows a short description, transport, and a per-server icon.
3. Click Install on the card you want.
4. The install dialog opens with three flavours depending on the server:
   • No auth needed (filesystem, fetch, memory, time, sequential_thinking, git, everything) - just click Install server.
   • Personal token (github, notion, linear, clickup, stripe, vercel, cloudflare, apify, ...) - paste your token in the single field, click Install. The dialog points to the exact provider settings page where the token can be generated.
   • OAuth (gmail, google_drive, google_calendar, slack, notion) - click Connect with X, finish the browser round-trip, you're done.
5. After install the dialog probes the server, populates its tool list in the Installed tab, and you can reference it from any app.yaml under tools.modules.mcp.

From the CLI

Same result, no UI:

bash

# MCP servers are configured in app.yaml under tools.modules.mcp
# See the MCP reference for configuration options

Path 2 - Inline custom server in app.yaml

For servers that aren't (yet) in the Hub catalog or that have very specific needs (private internal server, forked package, custom flags), declare the full config under modules.mcp.config.servers in your app.yaml.

yaml

tools:
  modules:
    mcp:
      config:
        servers:
          my-internal-server:
            transport: stdio                  # stdio | sse | streamable_http
            command: npx
            args: ["-y", "@my-org/private-mcp"]
            env:
              MYORG_API_KEY: "{{secret.MYORG_KEY}}"
            sandbox:
              permissions: [process.exec, net.http]
              allowed_hosts: [api.my-org.com]

The daemon installs the npm/pip package, registers the server, and connects on first agent turn. The same sandbox / rate_limit / middleware knobs as Catalog servers apply.

Referencing installed servers from app.yaml

Once a server is installed via Path 1, you don't repeat its configuration in your app.yaml. Use the short name:

yaml

tools:
  modules:
    mcp:
      config:
        servers:
          - github                # reference daemon-managed install
          - notion
          - filesystem

Or as a dict (lets you tack on per-server overrides):

yaml

tools:
  modules:
    mcp:
      config:
        servers:
          github: {}              # reference, no overrides
          notion:
            rate_limit_rpm: 30    # only override the rate limit
          my-internal-server:     # inline custom (Path 2 above)
            transport: stdio
            command: ...
            sandbox:              # REQUIRED for inline custom servers
              permissions: [process.exec, net.http]

Sandbox defaults

Bare references (- github) and empty-dict references (github: {}) auto-get the standard sandbox permissions: [process.exec, net.http] so the runtime doesn't reject the call at dispatch time. Inline custom servers (with transport: / command: / url:) must declare their sandbox: block explicitly - the compiler refuses the deploy otherwise.

A bare catalog id in YAML resolves from: servers you already installed in the dashboard, then Digitorn's built-in catalog defaults. If nothing matches, that server's tools are simply missing from the agent (check the Install UI).

Discovering what's referenceable

Open the Digitorn dashboard → Admin → MCP Servers → Installed (and Catalog for Hub entries). Use those server_id values in your app YAML.

Reasoning models - bump max_tokens

If your agent uses an OpenAI reasoning model (gpt-5*, o1, o3), keep max_tokens ≥ 4096. These models burn part of the budget on internal reasoning before producing visible output or tool calls; with the default 1024 you'll often see empty assistant turns and no tool invocation.

yaml

agents:
  - id: main
    brain:
      provider: openai
      model: gpt-5-mini
      max_tokens: 4096     # don't go below this for MCP-heavy apps

Non-reasoning models (Claude, GPT-4o, DeepSeek v3, Llama) are unaffected - 1024 is fine.

When the install fails

Common cases and their fixes:

Symptom	Root cause	Fix
'uvx' is not on PATH	uv not installed on the host	macOS: brew install uv ⋅ Linux: curl -LsSf https://astral.sh/uv/install.sh | sh ⋅ Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
'npx' is not on PATH	Node.js missing on the host	Install Node.js from nodejs.org or your package manager
npm install failed: 404	Upstream package was removed or renamed	Pick a different catalog entry or use Path 2 with the correct package name
HTTP 401 Unauthorized	Server requires auth not yet provided	Edit the server: dashboard → Installed → card → Configure
HTTP 404 ... (SDK reports "Session terminated")	The MCP endpoint URL is incorrect or has been retired	Verify the URL with the publisher; remove + reinstall with the correct address
MCP error -32603: Invalid response format	Transport mismatch - server speaks legacy HTTP+SSE but client opened streamable_http (or vice versa)	Switch transport: to the form the server actually speaks (sse ↔ streamable_http)
MCP server '<id>' has no sandbox permissions declared	Inline custom server in YAML without an explicit sandbox: block	Add sandbox: {permissions: [process.exec, net.http]} to the server config (bare references auto-inject the default)
Server X is already installed	A previous install succeeded but the row is still there	Uninstall via the card then reinstall, or use the existing row as-is

For the full troubleshooting reference, see the mcp module reference.