---
title: How to set up an MCP server for a real agent workflow
slug: harness-how-to-setup-mcp-server-agent-workflow
date: 2026-08-12
excerpt: "A reproducible guide to connecting an MCP server to an agent workflow: the six steps in order, working configs, what happens to the credential you paste in, the four failures I hit while building the integration, and where it honestly does not reach."
featured_image: "https://bbtxujdxvidaghmhxkqs.supabase.co/storage/v1/object/public/generated-images/blog-1786549919462-harness-how-to-setup-mcp-server-agent-workflow.webp"
featured_image_alt: Dark schematic diagram showing three boxes labelled Process on the left, each joined by a glowing amber line to a panel on the right labelled AI agent runtime. Every line passes through a small shield icon with a tick, and one grey line ends in a broken chain link instead of reaching the runtime.
canonical_url: https://cerevisor.com/blog/harness-how-to-setup-mcp-server-agent-workflow
updated_at: 2026-08-13T12:00:40.680015+00:00
---

# How to set up an MCP server for a real agent workflow

TLDR

Connecting an external tool server to an agent workflow is a four-field form followed by a series of small surprises: a credential that quietly resolves to nothing, a first tool call that stops to ask permission, a server that connects but reports zero tools. This is the working guide. Six steps in order, real configs, the four failures I hit while building the integration, and an honest list of the places it does not reach.

**By the founder of Cerevisor.** Last verified 12 August 2026 against Cerevisor 2.0.1. Methodology and source files at the end.

The most useful thing I learned building Model Context Protocol support into Cerevisor came from a bug that only shows up on the second run.

Model Context Protocol, usually shortened to MCP, is an open standard that lets a separate program hand a bundle of tools to an AI agent. It means an agent can use somebody else’s file reader, database client, or ticket-tracker without anyone writing custom glue for each one. A server that speaks it is not a website. It is a small program started on the same machine as the harness, running as a child process and talking over the same plain input and output pipes a terminal uses.

Here is the bug. A server needs a credential, supplied as an environment variable, which is just a named value handed to a program the moment it starts. If that name resolves to nothing, the program starts anyway. It connects. It lists its tools. The row in settings turns green. Then an agent calls one of those tools and gets an authentication error that reads exactly like the remote service is having a bad day.

That failure is no longer possible in Cerevisor, and the reason is one deliberate decision: when a stored credential reference cannot be resolved, the server does not start at all. It reports a specific error on its row instead, naming the variable that broke. Falling back to an empty value would have been the polite thing to do and the wrong thing to do, because it silently changes what the child program does while telling the operator everything is fine.

---

## Why the MCP quickstart stops working the moment a real workflow runs

Most MCP quickstarts end at “the server connected.” That is the easy half.

The hard half is everything the harness has to decide on the agent’s behalf. Which tools get merged into the agent’s catalogue. What happens when two servers both offer a tool with exactly the same name. Whether a call from an unfamiliar server should run unattended at two in the morning. What happens to the access token sitting in a configuration file on disk after the app closes.

Those four decisions are the difference between a demo and something that can run while nobody is watching. They are also where every surprise in this guide lives.

Key Insight

An MCP server is not an integration you configure once. It is a child process with a credential, a permission posture, and a failure mode, and the setup form is where all three get decided.

---

## MCP server setup in six steps

This is the sequence I use, in order. It takes a few minutes when nothing goes wrong, and it fails loudly rather than quietly when something does.

- **Run the server's own command in a terminal first** Before touching any settings screen, run the exact command from the server's documentation by hand. Most first-time failures are a missing runtime or a package name typo, and a terminal tells the truth faster than any status row will.

- **Give the server a short namespace name** The name becomes the prefix on every tool the server exposes, which is how two servers can each offer a file reader without one shadowing the other. Cerevisor's form accepts letters, digits, hyphens and underscores only, and rejects a name that already exists in the list. Short and boring wins: filesystem, github, postgres.

- **Split the command from its arguments** The command is the executable on its own. Every argument goes on its own line, in order, exactly as the server's documentation lists them. This is the step people get wrong most often, because published examples show one long shell string and the form wants it separated.

- **Add environment variables one per line, as name and value** These are passed to the child process on top of the harness's own environment. Anything the server needs to authenticate goes here rather than in the arguments, where it would sit in plain sight on the server's row.

- **Use Test connection before saving anything** Test connection starts the server, counts the tools it reports, then shuts it down again without writing a configuration entry. A test that reports zero tools is a real result, not a glitch, and it is much cheaper to learn that now than mid-run.

- **Save, then run one small workflow and watch the first tool call** In the automatic approval mode, the first call from a newly added server stops and asks. That prompt is the integration working correctly, not a misconfiguration, and the section below explains how to change it deliberately rather than by accident.

Here is a complete working entry, the official filesystem server scoped to one project directory. In the form it is four fields; this is what the harness stores.

```
{ "id": "fs-home", "name": "filesystem", "transport": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"], "env": {}, "enabled": true }
```

And this is what the agent then sees in its tool list, with the server name carried as a prefix so nothing collides with the built-in file reader or with a second server that happens to offer the same thing:

```
mcp__filesystem__read_file mcp__filesystem__write_file mcp__github__read_file # different server, no collision
```

A server that needs credentials looks like this in the form:

```
Name (namespace): github Command: npx Arguments: -y @modelcontextprotocol/server-github Environment vars: GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
```

---

## What happens to the token pasted into that environment variables box

Nothing good, in most tools. The value lands in a configuration file in plain text and stays there.

Cerevisor runs a migration pass on every app start, on every plan tier, that walks saved server entries looking for plain-text values that look like real secrets. Anything it finds moves into the operating system’s own credential store, and the configuration file keeps only a pointer. The stored entry changes shape from a string to a reference:

```
// before: readable by anything that can open the file "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here" } // after the next app start: a pointer into the OS credential store "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": { "encryptedRef": "mcpEnvLegacy:gh-main:GITHUB_PERSONAL_ACCESS_TOKEN" } } // after promoting it to a named vault entry (paid plans) "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": { "vaultSecretId": "b0f1…" } }
```

The pointer is resolved back to the real value at the moment the server is started, so the child process sees an ordinary environment variable and needs no awareness of any of this.

Two details are worth knowing because they change what to expect. First, the test for “looks like a real secret” is deliberately generous: known token prefixes for the common providers, plus any value of at least 20 characters that is not a file path, not a web address, and not an obvious flag word like true or production. Encrypting something that was never a secret costs nothing, since the same string comes back out. Missing a real one leaves it readable on disk. The asymmetry only points one way.

Second, the whole pass is skipped when the operating system cannot actually encrypt, which in practice means a Linux box without a keyring service installed. The values stay in plain text and a warning appears rather than a false green tick. Writing “encrypted” over an unencrypted file would be the more comfortable option and a lie.

On paid plans there is a second step that promotes those pointers into named vault entries, so the value stops being an anonymous slot and becomes something managed in one place alongside every other credential. The server row shows a badge for which of the three states each variable is currently in: still plain text, encrypted at rest, or backed by a vault entry.

---

## Why tools from a new MCP server ask before they run

Every harness with an automatic approval mode has to answer one question: which actions are routine enough to run unattended.

Cerevisor sorts every tool call into routine or consequential. Routine runs without interruption. Consequential stops and asks. Built-in tools get sorted by what they do, so reading a file is routine and deleting one is not. Tools that arrive from an MCP server are sorted differently: they are consequential by default, no matter what they claim to do, and that rule is checked before any other rule in the classifier.

The reason is that the harness has no way to know what a third-party tool does. A tool named after a harmless read can post to a public channel. The only party who can vouch for it is the person who added it, so the decision is theirs to make explicitly through a per-server Trust toggle. Marking a server trusted flips its tools to routine.

The same toggle does a second job that is easy to miss. It also decides how carefully the harness treats what those tools send back. Output from an untrusted server is handled as content that might be trying to influence the agent, which is the realistic threat model for anything that reads issues, emails, or web pages on the agent’s behalf. Trusting a server to act and trusting what it returns are the same grant here, on purpose, because separating them produces a setting nobody can reason about.

The harness cannot tell a safe third-party tool from a dangerous one. The person who added the server can. That is why the trust decision lives with them and defaults to no.

The rest of the industry is arriving at the same shape, one level up. GitHub shipped enterprise MCP allowlists on 6 August 2026, generally available rather than in preview. An allowlist here is simply a central list naming which servers are permitted, maintained by whoever owns the organisation rather than by each developer. As the GitHub changelog put it: “Enterprise owners can now centrally control which Model Context Protocol (MCP) servers [GitHub Copilot](/blog/copilot-vs-claude-code-decision-changed) clients are allowed to run.”

Two design details in that release are worth copying into any internal policy. Servers can be matched three ways, by web address for remote ones, by the command line for locally launched ones, and by the label a person assigned. And the policy fails closed, meaning a configuration that cannot be read or verified blocks the server rather than waving it through. Failing closed is the unglamorous choice and the correct one, for the same reason a credential that will not resolve should stop a server rather than start it empty.

---

## Four failures I hit connecting MCP servers, and the fix for each

**The row says connected, but the tool count is zero.** Connecting and asking a server what it can do are two separate exchanges, and the second one can fail on its own. When it does, the server is still registered as connected and the listing error is attached to the row rather than thrown away. The fix is almost always upstream: run the command by hand and read what the server prints to its error output. A server that needs a directory argument and did not get one will often connect and then have nothing to offer.

**The server refuses to start and names an environment variable.** This is the deliberate refusal from the opening. A credential reference points at a vault entry or keychain slot that no longer exists, usually because the entry was renamed or deleted. Re-point the variable at a live entry and the server starts. It will not start on a blank value, which is the whole point.

**Approval prompts keep arriving, run after run.** In the automatic mode, an untrusted server asks before each new kind of call, and untrusted is the default. Approving inside a session can be remembered for that session, so the prompts thin out as a run proceeds and then return on the next one. This is correct behaviour, not a bug. The fix is a deliberate one-click Trust on that server’s row, made after its tool list has actually been read rather than before.

**The server never appears in the pre-run input picker.** Some MCP servers expose resources, which are read-only chunks of data such as a file or a record that can be attached to a run before it starts. Many servers expose none. Cerevisor asks every server for its resources at connect time, treats “I do not support that” as simply zero resources, and never lets that lookup block or fail a startup. A server with no resources is not broken; the picker falls back to offering its zero-argument read tools instead.

None of this is specific to one harness, which is the genuinely reassuring part. [Claude Code](/blog/harness-supervisory-engineer-org-chart-box) shipped four releases between 8 and 11 August 2026, and three of them were MCP plumbing repairs. One fixed servers whose sign-in credentials were being read from the operating system’s credential store too slowly: “Fixed MCP OAuth servers on macOS intermittently failing with a burst of 401 errors, as if never authenticated, after a keychain read timed out”. Another fixed servers being shut down underneath a conversation that was still using them: “Fixed plugin-provided MCP servers being torn down when MCP servers are re-synced mid-session”.

Read those two entries as a maturity signal rather than a warning. MCP support across the industry has moved from feature announcement to maintenance surface, and the failures being fixed are timing, credentials, and lifecycle. Exactly the three things this guide keeps circling back to.

---

## The timeouts and counts worth watching when a server misbehaves

Four numbers, taken straight from the client that manages these connections. They are the budget every MCP server is held to, and knowing them turns a vague hang into a diagnosable event.

MCP operation timeouts in Cerevisor 2.0.1

OperationTimeout

Initial connect and handshake**15 seconds**
Asking the server for its tool list10 seconds
Reading one resource30 seconds
A single tool call**120 seconds**

A server that fails at fifteen seconds is a startup problem: wrong command, missing runtime, waiting on something interactive. A server that fails at a hundred and twenty is a workload problem: the tool is doing genuine work and needs a narrower query, not a longer wait.

The number that actually tells the truth about health is the tool count on the server’s row. It is read from the server itself at connect time rather than from anything the configuration claims, so a count that changes after an upgrade is a real signal that the server’s surface [changed underneath](/blog/resilient-headcount-hides-org-shift) the workflows using it.

One more thing worth knowing about timing. Enabled servers are started twice over, and neither start is wasted. The app pre-connects them during startup so the first run does not pay the spawn cost, and the run then asks for them again and gets the already-connected ones back. When the run finishes, every server started for it is shut down.

---

## Where MCP does not reach, and why that is worth knowing before starting

An integration guide that lists only capabilities is a brochure. These are the real edges.

**Only local child processes are supported.** Cerevisor speaks to MCP servers as programs it starts on the machine, not as remote endpoints reached over a network. A server published as a hosted service needs a local bridge. This is a real constraint and it removes a real exposure, because a server that only exists as a child process on one laptop is not sitting on the public internet waiting to be found. Adversa AI’s August security roundup relayed exactly how much looking is going on:

> "Across fourteen days of logs from one modest web host, a July 13 SANS ISC diary counted roughly 200 requests from 49 distinct source IPs."

Adversa AI, August 2026, reporting the SANS Internet Storm Center diary

That is one ordinary web server, in a fortnight, being probed for exposed agent infrastructure. Remote MCP has its own engineering problems in exchange. Google’s developer blog wrote on 5 August about why the protocol was reworked to stop depending on a remembered session, and described the symptom plainly. When a hosted server is run as several interchangeable copies for capacity, a follow-up request can land on a copy that has never met the client before: “Deploying behind a Kubernetes cluster with three pods meant a second request from a client would randomly hit another pod, returning a 400 Session Not Found error.” Local child processes never have that conversation. They have the different problems listed above.

**Two provider paths do not receive these tools.** When a workflow node runs through the Codex command-line provider, that tool surface belongs to Codex and Cerevisor’s MCP tools are not injected into it. The Cursor Agent provider accepts its own server configuration that can be passed through, but it does not share Cerevisor’s client, so connectivity there is a deployment question rather than a settings one. Both are documented limits rather than bugs, and built-in tools remain the right choice for those nodes.

**Pictures come back as placeholders.** MCP servers can return several kinds of content. Text is passed through in full. Images and binary payloads are flattened to a short text marker so an agent gets a coherent transcript rather than a broken blob.

**MCP is a paid-tier capability.** Server entries can be saved on any tier and they persist, but they do not start on the free tier and their tools are filtered out of the agent’s catalogue entirely rather than merely hidden in the interface. That distinction matters: a stray server left over from a trial cannot be invoked by an agent afterwards.

---

## How this MCP server setup was verified

Everything above was checked against the Cerevisor source on 12 August 2026, at application version 2.0.1. No figure here is calculated from any other figure; each timeout and threshold is quoted directly from the constant that defines it.

The specific places to re-check when a future version moves: the connection manager that owns server startup, tool listing, and the timeouts. The credential migration module that owns the secret heuristic and the resolve-or-refuse rule. The shared action classifier that owns the routine-versus-consequential decision for MCP tools. The settings tab that owns name validation and the Trust toggle. And the connect and disconnect test suite, which pins the tool-prefix format, the idempotent double-connect, and the structured failure path so a regression in any of them fails the build rather than a workflow.

The shipped [MCP servers guide in the Cerevisor docs](https://cerevisor.com/docs/guides/advanced/mcp-servers) carries its own last-verified date and is the version that gets updated first when behaviour changes. Anything here that disagrees with it means this page has aged and the docs are right.

---

## Start with one read-only server before anything writes

The setup that goes well almost always looks the same. One server. Read-only tools. A directory or a repository that would not matter much if something went sideways. Left untrusted for the first few runs so every call surfaces a prompt and the actual tool traffic becomes visible rather than theoretical.

Do that this week, before the packaging layer above MCP settles and makes it easier to add five servers at once than one. That layer is arriving quickly. On 6 August 2026, OpenAI, Microsoft, Amazon Web Services, Anysphere, which makes Cursor, and Vercel published a shared standard called Agent Plugins, which bundles an MCP server configuration into a portable folder that any supporting client can pick up. Six clients supported it on day one. It solves distribution properly, and it deliberately does not solve permissions, which its own analysts count as one of several areas left for later. Easier to install and no easier to trust is a combination worth being ready for.

Watching that first sequence of approval prompts is worth more than any amount of reading, including this. It shows which tools the agent reaches for, how often, and with what arguments, and that is the information needed to decide whether the server deserves the Trust toggle at all. Several of the servers I have connected did not earn it, and the prompts were what told me.

The interesting part of MCP was never the protocol. It is that connecting a tool server is the first moment an agent stops being a closed system and starts touching things that belong to other people. Everything difficult about it follows from that, and everything in this guide is one team’s attempt to make that moment boring.

#### Sources

- [MCP allowlists in enterprise managed settings](https://github.blog/changelog/2026-08-06-mcp-allowlists-in-enterprise-managed-settings/) - GitHub Changelog, 2026-08-06

- [MCP security best practices and resources: August 2026](https://adversa.ai/blog/top-mcp-security-resources-august-2026/) - Adversa AI, 2026-08-06

- [Scaling AI Agent Infrastructure with the MCP Stateless updates](https://developers.googleblog.com/scaling-ai-agent-infrastructure-with-the-mcp-stateless-updates/) - Google Developers Blog, 2026-08-05

- [Claude Code changelog, versions 2.1.225 to 2.1.228](https://code.claude.com/docs/en/changelog) - Anthropic, 2026-08-11

- [Introducing Agent Plugins](https://vercel.com/blog/introducing-agent-plugins) - Vercel, 2026-08-06

- [Agent Plugins 1.0: What the New Open Standard Means for Your Codex CLI Plugin Strategy](https://codex.danielvaughan.com/2026/08/08/agent-plugins-1-0-open-standard-codex-cli-portable-skills-mcp-packaging/) - Codex Knowledge Base, 2026-08-08

- [MCP servers](https://cerevisor.com/docs/guides/advanced/mcp-servers) - Cerevisor Documentation, 2026-07-30

- [Model Context Protocol](https://modelcontextprotocol.io) - Anthropic / MCP