MCP Servers

MCP (Model Context Protocol) servers are sidecar processes that expose extra tools to your agents — connect them to Linear, your file system, a database, Slack, or anything else with an MCP integration, and your agents can call those tools the same way they call built-in ones.

How It Works

By default, an agent comes with a fixed set of built-in tools: read and write files, run shell commands, route messages to other agents, open windows, ask the user a question. Anything beyond that — opening a Linear issue, querying a Postgres database, posting to Slack — requires an MCP server. The MCP server runs as a small process on your machine; it advertises a list of tools and their arguments; and the agent’s CLI hands those tools to the model as callable options. When the model decides to use one, the call goes through the MCP server, the server does the work, and the response flows back into the agent’s transcript as a tool result.

Servers are described as configuration, not code. You give Viberia a command to run (an executable or npx invocation), an optional list of args, and an optional set of environment variables (typically used to pass API keys). Viberia starts the server when the agent needs it, supervises it, and surfaces tool calls as cards in Agent Chat. When the agent shuts down or its scope changes, the server is cleaned up.

Three scopes: user, building, agent

MCP servers can be attached at three levels, and an agent’s available servers are the union of the three:

User scope — attached in Settings → MCP Servers. Available to every agent in every building of every project. Use this for tools that benefit your whole world — Brave Search, a Slack workspace bot, or filesystem access scoped to a directory you use across projects.
Building scope — attached in the building’s window (see Building Window). Available to every agent inside that building. Use this for tools that belong to one workflow — a Postgres connection for a specific analytics project, the Linear server for the Linear building.
Agent scope — attached in the agent’s gear menu, in the MCP tab (see Agent Chat). Available only to that one agent. Use this for one-off tools — a custom MCP server you’re prototyping, or a per-agent API key for the same provider.

Within a single agent, server lists from all three scopes are merged. If two servers have the same name across scopes, the narrower scope wins — an agent-level server overrides a building-level server with the same name, and either overrides a user-level one.

Adding a server manually

The MCP settings panel at each scope has the same shape. Click Add server and you’ll fill in:

Name — a short identifier you’ll see in tool cards. Keep it lowercase and stable.
Command — the executable to run. Often npx, node, python, uvx, or a direct path to a binary.
Args — the arguments passed to the command, as a list. For Node packages this is usually the package name plus options; for binaries, the flags.
Environment variables — key/value pairs, typically API keys (LINEAR_API_KEY, BRAVE_API_KEY).

Save the server and Viberia attaches it to the chosen scope. The next time an agent in that scope starts (or after a restart), the server is launched and its tools appear in the model’s tool list.

Note: Most MCP servers ship as Node packages installable through npx. If npx isn’t on your PATH, set an absolute path or install the package globally and call its binary directly.

Status badges

Once attached, each server shows a status badge: running (green), stopped (gray), or errored (red). Click an errored server to expand its log — most failures are missing API keys, an executable that isn’t on PATH, or a malformed argument list.

How agents call MCP tools

When the model decides to use an MCP tool, the call renders in the transcript as an MCP tool card: the server name, the tool name, the arguments, and the response. In Standard permission mode you’ll see a permission card first (Allow / Allow always / Deny). In YOLO mode the tool runs immediately. Tool output is shown collapsed by default and can be expanded for full detail.

Installing Servers with /learn-mcp

The easiest way to add a server is to invoke /learn-mcp on any agent. The skill knows the canonical configuration for a curated set of common servers and walks you through the missing pieces (API keys, scopes, paths). It then writes the server into the scope you pick — user, building, or agent.

A typical install looks like this:

/learn-mcp linear

The agent confirms the Linear MCP package, asks for the scope, asks for your API key, and saves the entry. After it reloads the registry, the server appears in the panel and the agent can call its tools.

You can also pass a name the skill doesn’t recognize, in which case it falls back to a generic prompt: “what command, what args, what env.” This works for npm packages, local binaries, and git URLs.

Canonical configs `/learn-mcp` knows

/learn-mcp ships with vetted configurations for the most common servers, so you don’t have to look up package names or env variables:

Name	Provides	You’ll need
`linear`	Backlog, issue, and cycle operations on Linear.	A Linear API key.
`filesystem`	Scoped read/write outside the project root.	A list of allowed directories.
`postgres`	SQL queries against a Postgres database.	A connection URL.
`slack`	Read/send Slack messages, channel listing.	A Slack bot token.
`sentry`	Read issues, releases, and events from Sentry.	A Sentry auth token.
`brave-search`	Web search via the Brave Search API.	A Brave Search API key.
`sqlite`	Query and modify a local SQLite database.	A database file path.
`google-drive`	Read and write Google Drive files.	An OAuth token.
`git`	Git operations beyond the built-in shell (status, log, diff).	A repo path (defaults to the project’s `folder_path`).

If a server you want isn’t in this list, use the generic flow — /learn-mcp some-other-server — and the skill will ask for command, args, and env.

Note: API keys, tokens, and connection URLs are stored as part of the server’s environment configuration. Use scoped tokens whenever the provider supports them — read:org instead of full repo write, a read-only Postgres user instead of an admin role.

Common Pitfalls

A few failure modes account for nearly every MCP issue you’ll hit:

Missing API keys. The server starts but its tools fail at first call. Open the server in the MCP panel and add or correct the env variable.
Command not on PATH. If npx, node, or python isn’t on the shell’s PATH for the user Viberia runs as, the server fails to start. Use an absolute path to the binary, or install the package globally and point at its installed bin.
Wrong package name. Typos in the package or args fail loudly in the server log. Click the errored server to expand it.
Permission denied at the OS level. A filesystem MCP can only read what your account can read. You may need to grant Full Disk Access to Viberia in Settings → Permissions.
Port conflicts. Most MCP servers don’t listen on ports, but some do. If a server reports a bind error, another instance is probably already running — restart Viberia to clean up zombies.
Stale credentials. Tokens expire. If a server worked yesterday and 401s today, rotate the key in the provider’s dashboard and update the env variable.
Scope confusion. A tool you expected to see is missing because the server is attached at a narrower scope than the agent you’re using. Open the agent’s MCP tab and verify the merged list.

When a server is acting up, the fastest debug path is: click the server in its panel → read the log → fix the env variable or the command → save → wait for the green badge.

Skill vs MCP — What’s the Difference?

Skills and MCP servers both extend what an agent can do, but they sit in different layers of the stack. Use this comparison when you’re unsure which one you need.

	Skill	MCP Server
What it is	A packaged workflow the agent runs end-to-end.	A set of callable tools the agent can invoke during any workflow.
Who invokes it	You, with `/<name>` in chat.	The agent, automatically, as part of solving a task.
Scope of work	Multi-step, opinionated procedure (draft a PRD, run a loop).	A single capability (read a file, query a database, fetch a URL).
Configuration	A `SKILL.md` bundle in `~/.viberia/skills/`.	A command + args + env block; runs as a sidecar process.
Where to install	Settings → Skills (user); building/agent picker (scope).	Settings → MCP Servers (user); building MCP section; agent MCP tab.
How to install	`/learn-skill` or drop into the skills folder.	`/learn-mcp` or add manually in Settings → MCP Servers.
Typical example	`/draft-a-prd` — produces a `PRD.md`.	`linear` MCP — exposes `create_issue`, `list_issues`.

A useful intuition: a skill is a recipe, an MCP server is a tool in the kitchen. A skill might call several MCP tools as part of its recipe, and an MCP server might be used by many different skills. See Skills (Slash Commands) for the matching catalog.

Use Cases

Wire Viberia to your team’s services. Attach linear and slack at the user scope so every agent can interact with your stack.
Give one building a database connection. Add postgres at the building scope so only the analytics CodeForge agents can run SQL, leaving the rest of your world untouched.
Prototype a custom MCP server on one agent. Attach an experimental server at the agent scope and iterate without disturbing other agents.
Layer a per-agent API key on a global server. Attach the same server name at the agent scope with different credentials to override the user-level token for that agent only.
Trace a tool failure. Open the errored server in the MCP panel, read the log, fix the env variable, and watch the badge turn green.
Hand a workflow a sharper toolset. Combine a skill (e.g. /plan-sprint) with the matching MCP server (linear) to give the skill direct write access.

Limitations

MCP servers are external processes that you trust. A misbehaving or malicious server runs with your user account’s permissions. Install only servers from sources you trust, and prefer scoped tokens when possible.
Servers are started on demand and supervised by Viberia. When you quit the app, all servers are stopped — long-running MCP servers do not persist across launches.
Server lists are merged across scopes by name. If you accidentally name two different servers the same thing at different scopes, the narrower wins; rename to avoid surprises.
Edits to a server’s command, args, or env take effect when the server next starts. Many servers do not hot-reload — restart the agent (or Viberia) to pick up changes.
Some servers require OS-level permissions (Full Disk Access, network egress, keychain entries). Failures of this kind don’t always surface in the MCP log — check Settings → Permissions when a server reports cryptic errors.
The list of canonical configs /learn-mcp knows is a curated subset; anything outside it works fine but requires manual command/args/env.