> ## Documentation Index
> Fetch the complete documentation index at: https://docs.barndoor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bring your own local MCP server

> Package an npm or PyPI MCP server into a signed Mac executable, publish it to your Barndoor catalog, pin its signing key with MDM, and let employees run it under Barndoor policy through Bridge.

> [!NOTE]
>
> Barndoor Bridge is in Early Access. These pages are not listed in the navigation. Overview: `/how-tos/barndoor-bridge/overview` · Using Bridge: `/how-tos/barndoor-bridge/using-bridge` · Install with MDM: `/how-tos/barndoor-bridge/install-with-mdm` · Bring your own local MCP: `/how-tos/barndoor-bridge/publish-local-mcp`

Some MCP servers have to run on each employee's Mac: a Temporal or Auth0 server from npm or PyPI, an internal on-call tool, a deploy helper. This guide is for the admin who publishes one to the whole fleet. When you're done, every managed Mac runs only the exact build you released, only after your IT pinned your signing key, and only for the tools your policy allows.

It follows a real end-to-end run: publishing the open-source [Temporal](https://pypi.org/project/temporal-mcp-server/) (PyPI) and [Auth0](https://www.npmjs.com/package/@auth0/auth0-mcp-server) (npm) servers to Barndoor's own organization. Quoted output is real.

## How your own local MCP server runs under Bridge

In sessions Bridge launches, there is exactly one way to run a local MCP server:

* **A single signed executable per Mac architecture.** Bridge downloads it over HTTPS from a host you control and runs it over stdin/stdout. No `npx`, no `uvx`, no sibling files.
* **A signed release description in your Barndoor catalog.** It names the download URL and sha256 of each build, the command-line arguments, and the environment variables the server may see. Any edit breaks the signature.
* **A publisher key pinned by your MDM.** Each Mac trusts a release only if its signature verifies against a public key in the Barndoor managed-settings profile, and downloads it only from the hosts that profile allows for that key.

Two things people try first don't work in Bridge:

* **Claude Desktop's own local MCP setting is off.** Bridge launches Claude Desktop with its "add a local MCP server" option disabled, so a server added in Claude Desktop's settings never runs.
* **Per-machine approval is ignored.** `barndoor local-mcp trust` approves a build on one machine for ungoverned CLI sessions only. In Bridge such a server shows **Local approval only** and doesn't run.

| Who | Holds | Can't do on its own |
| - | - | - |
| **Your publisher** | The private signing key. Packages, signs and publishes each release. | Get code onto a Mac whose MDM profile doesn't pin the key. |
| **Your IT (MDM)** | The public key and its allowed download hosts, in the Barndoor managed-settings profile. | Change what a release contains. |
| **Barndoor** | The signed release in your catalog, the installation, and your policy. | Change the release: any edit breaks the signature. |

When a session starts, Bridge verifies the signature against the pinned key, downloads the build for that Mac from an allowed host (it does not follow redirects), checks its sha256, keeps a read-only copy, and re-checks the sha256 on every launch. Every tool call then goes through Barndoor policy and the audit log. If any check fails, the server is skipped and nothing runs.

## Overview

| Step | Who | How often |
| - | - | - |
| [1. Package the server](#step-1-package-the-server) | Publisher | Every release |
| [2. Generate a publisher key](#step-2-generate-a-publisher-key) | Publisher | Once |
| [3. Write the credential and configuration schemas](#step-3-write-the-credential-and-configuration-schemas) | Publisher | Once, if the server needs them |
| [4. Sign](#step-4-sign-the-release) | Publisher | Every release |
| [5. Host the builds](#step-5-upload-the-builds) | Publisher | Every release |
| [6. Publish to your catalog](#step-6-publish-to-your-catalog) | Publisher (org admin) | Every release |
| [7. Install for the organization](#step-7-install-it-for-the-organization) | Org admin | Once |
| [8. Set a policy](#step-8-set-a-policy-required) | Org admin, in the admin UI | Once |
| [9. Users connect it](#step-9-users-connect-it) | Each employee | Once |
| [10. Pin the key with MDM](#step-10-pin-the-key-with-mdm) | IT | Once per key |
| [11. Verify on a Mac](#step-11-verify-on-a-mac) | Anyone | As needed |

Steps 7 to 10 are one-time. After that, a new release is steps 1 and 4 to 6, and all of them run from the command line, so a CI pipeline can do it.

## Before you start

* **Bridge 0.1.218 or later** on your managed Macs, which needs **macOS 15 Sequoia or later** ([Install with MDM](https://docs.barndoor.ai/how-tos/barndoor-bridge/install-with-mdm)). Bridge installs the `barndoor` command used below. Check with `barndoor version`; Bridge 0.1.218 prints `v0.1.218 (cli release v0.1.288)`.
* **A Barndoor organization admin** signed in on the publishing Mac (`barndoor auth login`).
* **Local MCP management enabled** for your organization. If **MCP Servers → Add MCP Server** has no **Local** filter, contact Barndoor.
* **An HTTPS host** that every Mac can download from **without signing in** and **without a redirect to another host**: a public storage bucket (Google Cloud Storage, Amazon S3, Azure Blob), a CDN, or an internal web server on your network. GitHub release downloads don't work, because they redirect to another host.
* **An MDM admin** who can change your Barndoor managed-settings profile.
* **For packaging:** a Mac. To build the Intel version on Apple silicon, install Rosetta 2 (`softwareupdate --install-rosetta`). Nothing else needs installing; `barndoor local-mcp package` downloads its own pinned build tools.

## Step 1: Package the server

Bridge downloads **one self-contained executable** per platform: `darwin/arm64` (Apple silicon) and `darwin/amd64` (Intel). Most MCP servers ship as an npm or PyPI package you'd normally start with `npx` or `uvx`. `barndoor local-mcp package` turns one into both executables:

```bash theme={null}
barndoor local-mcp package pypi:temporal-mcp-server==1.12.0 --out pkg/temporal --name temporal-mcp

barndoor local-mcp package npm:@auth0/auth0-mcp-server@0.1.0-beta.19 --out pkg/auth0 \
  --name auth0-mcp --args run --args --read-only \
  --env AUTH0_TOKEN=placeholder --env AUTH0_DOMAIN=example.us.auth0.com
```

It writes:

```text theme={null}
pkg/temporal/darwin-arm64/temporal-mcp
pkg/temporal/darwin-amd64/temporal-mcp
pkg/temporal/tools.json      the server's tools, ready for sign --tools-from
```

and prints the `sign` command to run next. In our run, Auth0 took about 5 seconds and Temporal about 50.

* **Versions must be exact:** `@1.2.3` for npm, `==1.2.3` for PyPI.
* **`--name`** is the executable's file name. It becomes `{executable}` in the download URL.
* **`--entry`** picks the npm bin or PyPI console script when a package has more than one.
* **`--args` and `--env` are for the smoke test only.** `package` starts each build with only `PATH`, an empty `HOME` and your `--env`, and checks that it answers MCP `initialize` and `tools/list`. Both architectures must list the same tools. Use `--env` for placeholder credentials a server needs just to start. A published server gets only the variables you allow when signing, and `package` reminds you: `The smoke test set AUTH0_DOMAIN, AUTH0_TOKEN. A launched server gets only --env-allowlist variables, so add them there or bind them per user with --credential-schema.`
* npm servers are compiled with bun, with `.env` and `bunfig.toml` loading turned off, so a stray `.env` can't feed the server variables you didn't allow. `package` also fixes the two runtime loads that usually break a compiled npm server: native modules that pick their `.node` file at runtime, and `package.json` read through `createRequire`. Any other load whose path is only known at runtime fails the build, naming the file and line.
* PyPI servers are frozen with PyInstaller from prebuilt wheels only; the Intel build runs under Rosetta. One-file PyInstaller builds unpack themselves on each start, so the first response takes a few seconds.
* The build tools (bun, uv, PyInstaller) are pinned versions, downloaded once into `~/Library/Caches/barndoor/local-mcp-package` and checked against sha256 sums built into `barndoor`. Package install scripts never run.

> [!WARNING]
>
> Don't publish a small wrapper that runs `npx` or `uvx`. The signature would cover only the wrapper, and whatever the registry serves at launch would run unverified. Bundle the server and all its dependencies into the file you sign.

A server written in Go is already one file. Build it once per architecture (`GOOS=darwin GOARCH=arm64`, then `GOARCH=amd64`) into the same folder layout, with the same file name in each.

> [accordion] Packaging by hand, without the package command
>
> If `package` can't build your server, or you build in your own pipeline, these are the recipes it automates.
>
> **npm, with bun:**
>
> ```bash theme={null}
> npm install @auth0/auth0-mcp-server@0.1.0-beta.19
> bun build --compile --minify \
>   --no-compile-autoload-dotenv --no-compile-autoload-bunfig \
>   --target=bun-darwin-arm64 \
>   node_modules/@auth0/auth0-mcp-server/dist/index.js \
>   --outfile pkg/auth0/darwin-arm64/auth0-mcp
> # repeat with --target=bun-darwin-x64 --outfile pkg/auth0/darwin-amd64/auth0-mcp
> ```
>
> * **Always pass `--no-compile-autoload-dotenv --no-compile-autoload-bunfig`.** Without them a compiled program reads `.env` and `bunfig.toml` from whatever folder it starts in. In our run, an Auth0 build compiled without these flags started with credentials from a `.env` in its working folder; the build compiled with them refused.
> * Replace a native module's computed `require('prebuilds/' + process.platform + …)` with a literal path to the target's `.node` file. For Auth0 that's `@github/keytar/lib/keytar.js`: start `loadNativeAddon()` with `return require('../prebuilds/darwin-arm64/keytar.node')`, or `darwin-x64` for the Intel build.
> * Inline `require('../../package.json')` loaded through `createRequire`. Otherwise the compiled file fails with `error: Cannot find module '../../package.json' from '/$bunfs/root/…'`. For Auth0 that's `dist/utils/package.js` and `dist/utils/analytics.js`.
>
> **PyPI, with PyInstaller:** write a three-line `entry.py` that calls the server's `main`, then:
>
> ```bash theme={null}
> uv venv -p 3.12 .venv-arm64
> VIRTUAL_ENV=$PWD/.venv-arm64 uv pip install temporal-mcp-server==1.12.0 pyinstaller
> .venv-arm64/bin/pyinstaller -y --onefile --name temporal-mcp --distpath pkg/temporal/darwin-arm64 \
>   --collect-all temporalio --collect-all temporal_mcp --exclude-module mcp.cli entry.py
>
> uv python install cpython-3.12-macos-x86_64
> uv venv -p cpython-3.12-macos-x86_64 .venv-x64
> VIRTUAL_ENV=$PWD/.venv-x64 uv pip install --only-binary :all: temporal-mcp-server==1.12.0 pyinstaller
> arch -x86_64 .venv-x64/bin/python -m PyInstaller -y --onefile --name temporal-mcp --distpath pkg/temporal/darwin-amd64 \
>   --collect-all temporalio --collect-all temporal_mcp --exclude-module mcp.cli entry.py
> ```
>
> * Don't `--collect-all mcp`: it imports `mcp.cli`, which fails the build with `SystemExit: 1` from `mcp/cli/cli.py`.
> * Install the Intel dependencies with `--only-binary :all:`. Otherwise uv compiles packages such as `cryptography` from source and fails with `error[E0463]: can't find crate for 'core'`.
> * Run the Intel PyInstaller as `python -m PyInstaller`; `arch -x86_64 .venv-x64/bin/pyinstaller` fails with "isn't executable".
>
> **Tool list:** write `tools.json` yourself. It's a JSON array of `{name, description, input_schema}`. A saved MCP `tools/list` result uses different field names and is refused by `sign` with `must be a JSON array of {name, description, input_schema}`. Convert it:
>
> ```bash theme={null}
> python3 -c "import json;t=json.load(open('tools-raw.json'));json.dump([{'name':x['name'],'description':x.get('description',''),'input_schema':x.get('inputSchema') or {}} for x in t],open('tools.json','w'))"
> ```
>
> Check each build before signing by starting it with an empty environment, for example `env -i PATH=/usr/bin:/bin HOME=$HOME pkg/temporal/darwin-arm64/temporal-mcp --host localhost:7233 --namespace default`.

## Step 2: Generate a publisher key

Run this once, signed in to the organization that will publish:

```bash theme={null}
barndoor local-mcp keygen --name release-2026 --allowed-host releases.example.com --out ./publisher-key
```

```text theme={null}
Wrote tenant publisher key to …/publisher-key
  organization: <your organization ID>  (from your signed-in session)
  key_id:       tenant:<your organization ID>:release-2026
  public_key:   Qz2VFzUFBtFvFBLrsOFZrioBSbJO+GRG/kMwkdOMxl0=
  fingerprint:  be05cc14  (what 'barndoor doctor' shows once the key is pinned)

Add this entry to the publisher_keys array of the managed-prefs MDM profile:
<dict> … </dict>
```

* The key is bound to your organization's ID. Pass `--org <organization ID>` only to target a different organization you belong to.
* `--allowed-host` is the host your builds download from. Repeat it for more than one. Without it, the printed entry carries a placeholder host that fails closed.
* `--out` gets `ed25519.seed` (the **private** key, mode 0600), `ed25519.pub` and `key_id`. Hand the printed `<dict>` and fingerprint to IT for [Step 10](#step-10-pin-the-key-with-mdm).

> [!WARNING]
>
> **Put `ed25519.seed` in a secret store right away** (your CI secret store, a cloud secret manager, or a password manager), and never in a temporary folder or a git checkout. Anyone holding it can publish servers your fleet will run.
>
> We lost our first walkthrough key when a macOS update rebooted the Mac and cleared the temporary folder it was in. Nothing had been pinned yet, so switching keys cost nothing. Once a fleet pins a key, losing its seed means generating a new key and rolling a new MDM profile to every Mac before you can ship another release.

Prefer a host only your organization controls, such as your own release domain. A shared host like `storage.googleapis.com` lets this key's releases download from any bucket on it. Each build is still pinned by its sha256 in the signed release, but a dedicated host keeps the allowed list meaningful.

## Step 3: Write the credential and configuration schemas

Skip this step if the server needs neither per-user secrets nor admin settings.

### Per-user credentials

If each employee supplies their own secret, such as an API key, declare it in a credentials file. When a user connects the server, Barndoor asks for these fields and passes each one to the server as the environment variable you name.

```json temporal-credentials.json theme={null}
{
  "fields": [
    {
      "name": "temporal_api_key",
      "label": "Temporal Cloud API key. Leave blank for a self-hosted Temporal server.",
      "type": "password",
      "required": false,
      "location": "env",
      "env_var": "TEMPORAL_API_KEY"
    }
  ]
}
```

* `name`: lowercase letters, digits and `_`, starting with a letter.
* `type`: `"password"` (masked) or leave it out.
* `location`: always `"env"`.
* `env_var`: Barndoor refuses `PATH`, `HOME`, `DYLD_*`, `NODE_*` and `PYTHON*`.
* A blank optional field is left out of the server's environment.

### Configuration values

Settings that are the same for everyone, such as a server address, belong in the arguments as `{{config.<key>}}` placeholders. The admin fills them in when installing. Declare them in a configuration schema, which you pass when you publish:

```json temporal-config-schema.json theme={null}
{
  "type": "object",
  "additionalProperties": false,
  "required": ["host", "namespace"],
  "properties": {
    "host": {
      "type": "string",
      "description": "Temporal frontend host:port, e.g. localhost:7233 or <namespace>.<account>.tmprl.cloud:7233",
      "minLength": 1,
      "maxLength": 255
    },
    "namespace": {
      "type": "string",
      "description": "Temporal namespace, e.g. default",
      "minLength": 1,
      "maxLength": 255
    }
  }
}
```

* A closed object: `"additionalProperties": false`.
* Properties are `string`, `boolean`, `integer` or `number`, with only `type`, `description`, `enum`, `minLength`, `maxLength`, `minimum` and `maximum`. **No `default`.**
* Property names: lowercase letters, digits and `_`, starting with a letter.

## Step 4: Sign the release

Start from the `sign` command `package` printed, and add your key, download URL, arguments and schemas:

```bash theme={null}
barndoor local-mcp sign \
  darwin/arm64=pkg/temporal/darwin-arm64/temporal-mcp \
  darwin/amd64=pkg/temporal/darwin-amd64/temporal-mcp \
  --ref-name temporal --version 1.12.0 \
  --url-template 'https://releases.example.com/temporal/{version}/{platform}/{executable}' \
  --key ./publisher-key \
  --args=--host --args='{{config.host}}' --args=--namespace --args='{{config.namespace}}' \
  --env-allowlist PATH,HOME \
  --tools-from pkg/temporal/tools.json --credential-schema temporal-credentials.json \
  --out signed/temporal-1.12.0
```

```text theme={null}
Signed com.barndoor.tenant.<org>.temporal 1.12.0 with tenant:<org>:release-2026 (fingerprint be05cc14); signature verified.
  …/envelope.json  …/tools.json (31 tools)  …/manifest.json
Upload each binary, unchanged, to:
  darwin/amd64   https://releases.example.com/temporal/1.12.0/darwin-amd64/temporal-mcp  (sha256 …)
  darwin/arm64   https://releases.example.com/temporal/1.12.0/darwin-arm64/temporal-mcp  (sha256 …)
The MDM publisher_keys entry for tenant:<org>:release-2026 must list allowed_hosts: releases.example.com
```

| Option | What it does |
| - | - |
| `<os>/<arch>=<file>` | One per build. |
| `--ref-name` | The server's name in your catalog. The first publish also uses it as the slug. |
| `--version` | Must be `X.Y.Z`. Fold a prerelease into the patch number: we published Auth0 `0.1.0-beta.19` as `0.1.19`. |
| `--url-template` | Where each build will be downloaded from. `{version}`, `{platform}` (such as `darwin-arm64`), `{os}`, `{arch}` and `{executable}` (the file name) are filled in. |
| `--args=<token>` | One per command-line argument, in order. `{{config.<key>}}` inserts a configuration value. |
| `--env-allowlist` | The only environment variables the server receives, plus any per-user credentials. `PATH,HOME` is usually enough. |
| `--tools-from` | The `tools.json` from `package`. Required with `--credential-schema` (otherwise `credentialed servers cannot use ambient credentials for tool discovery`), and best in CI so the server never runs next to the signing key. |
| `--credential-schema` | The credentials file from Step 3. |
| `--setup-command` | A subcommand users may run once, such as a sign-in. See [Servers that need a one-time sign-in](#servers-that-need-a-one-time-sign-in). |
| `--min-cli` | The oldest CLI allowed to run the server. Leave the default; don't lower it. |

`sign` writes `envelope.json` (the signed release), `tools.json` and `manifest.json` (the decoded release, for review) to `--out`. The download URL is part of what you sign, so moving the builds later means signing again.

## Step 5: Upload the builds

Upload each file, **byte for byte unchanged**, to the URL `sign` printed. If a file differs by one byte from what you signed, Macs refuse it.

For example, with a public Google Cloud Storage bucket:

```bash theme={null}
gcloud storage cp pkg/temporal/darwin-arm64/temporal-mcp gs://<bucket>/temporal/1.12.0/darwin-arm64/temporal-mcp
gcloud storage cp pkg/temporal/darwin-amd64/temporal-mcp gs://<bucket>/temporal/1.12.0/darwin-amd64/temporal-mcp
curl -sI https://storage.googleapis.com/<bucket>/temporal/1.12.0/darwin-arm64/temporal-mcp   # expect HTTP 200, no redirect
```

Upload before you publish: as soon as a release is published, Macs that have it installed can start downloading it.

## Step 6: Publish to your catalog

```bash theme={null}
barndoor local-mcp publish signed/temporal-1.12.0 \
  --name "Temporal (local)" --description "Query and manage Temporal workflows" \
  --configuration-schema temporal-config-schema.json
```

```text theme={null}
Published com.barndoor.tenant.<org>.temporal 1.12.0 as "temporal" (catalog id …, 31 tools).
Next, once, in the platform UI: install it for the organization and set its policy.
```

* The entry is visible only to your organization. Publishing installs nothing.
* Later publishes of the same `--ref-name` **update the entry in place** and refresh every installation of it: `Updated "auth0" (catalog id …) from 0.1.19 to 0.1.19 (10 tools); its installations pick up the new version.` The name, description and configuration schema stay as they are unless you pass them again. An older version is refused unless you pass `--allow-downgrade`.
* You must be an admin of the organization the key belongs to. In CI, set `BARNDOOR_CLIENT_ID` and `BARNDOOR_CLIENT_SECRET` to your organization's Terraform provider credential (**Settings → API Tokens**) instead of signing in. `install` in the next step uses the same credentials.

To publish without the command line, use the admin UI: **MCP Servers → Add MCP Server**, choose the **Local** filter, and open **Add to catalog**. Paste `envelope.json` into **Signed manifest envelope** and `tools.json` into **Tools**, check the **Decoded manifest** and **Key id** it shows, and declare the same settings under **Configuration schema**.

## Step 7: Install it for the organization

Installing is a one-time step. From the command line, with the same admin sign-in or CI credentials as `publish`:

```bash theme={null}
barndoor local-mcp install temporal --config host=localhost:7233 --config namespace=default
```

```text theme={null}
Installed (created) temporal.
id: …
slug: temporal
name: Temporal (local)
enabled: true
availability: opt_in
```

* `<catalog>` is the catalog entry's slug, id or ref.
* It's safe to run again, for example from CI on every release. A second run updates the installation and keeps anything you don't pass. Passing `--config` or `--config-file <json>` replaces the whole configuration.
* Configuration is checked against the entry's schema before anything is sent, and values are never printed: `Error: config key "bogus" is not declared by this catalog entry; declared keys: host, namespace`.
* `--disabled` / `--enabled` turn the installation off or on for everyone.
* `--availability opt_in|required` chooses whether each user opts in (the default) or every Mac runs it. It needs a Barndoor platform release from v2.53 on; leave it out otherwise.

**In the admin UI instead:** go to **MCP Servers → Add MCP Server**, choose the **Local** filter, find your entry, and select **Add New**. Fill in **Name**, **Slug**, **Who gets it** and **Configuration**, and save.

To change an installation later, open the server under **MCP Servers**. Its **Local capability** card shows the **Enabled** switch and **Configure**, which opens the same settings:

![The Configure dialog for Temporal (local): Enabled switched on, Who gets it set to Users who connect it (the other choice is Everyone), host localhost:7233 and namespace default, with Cancel and Save](https://mintcdn.com/barndoor/72VeZGR96UrrQTrS/images/barndoor-bridge/local-mcp-admin-install.png?fit=max\&auto=format\&n=72VeZGR96UrrQTrS\&q=85\&s=3a295daa015953e533c4175ef50bea45)

With the default availability, nobody gets the server until they connect it ([Step 9](#step-9-users-connect-it)). Right after installing, a Mac's sync still reports `0 managed local MCP`.

## Step 8: Set a policy (required)

> [!WARNING]
>
> **An installed, connected server does nothing until a policy grants its tools.** Barndoor denies by default. Without a policy every call fails with `This tool is blocked by policy.`, the server's tools don't appear in tool search, and an agent describing a tool gets `tool "list_workflows" on server "temporal" is denied by policy`.

Policies are set in the admin UI. Create an access policy for the server in the **Access Control Center** ([Managing Policies](https://docs.barndoor.ai/how-tos/manage-policies.md)):

1. Create a policy. On the **AI Agent** step, choose the agents it covers, for example all of them.
2. On the **MCP Server** step, choose the new server. You can't change the server after saving.
3. In the tool matrix on the same step, the **All Users** column is the baseline for everyone. Use **Add Group/Role** for narrower audiences. Set each tool to **Always Allow** (check), **Needs Approval** (shield) or **Off** (crossed circle). The **Set all** menu at the top of a column sets every tool at once; then change the exceptions one by one ([Granular Tool Use Confirmations](https://docs.barndoor.ai/how-tos/tool-confirmations.md)).
4. Finish **Policy Details** and **Policy Rules**, then save and activate the policy. It applies on the next tool call; nobody needs to restart.

![The policy wizard on its MCP Server step for Temporal (local): the All Users column shows 12/31 tools allowed, write tools such as Cancel Workflow and Create Schedule set to Needs Approval, and read tools such as Count Activities and Describe Workflow set to Always Allow](https://mintcdn.com/barndoor/72VeZGR96UrrQTrS/images/barndoor-bridge/local-mcp-policy-matrix.png?fit=max\&auto=format\&n=72VeZGR96UrrQTrS\&q=85\&s=b981afd4fc157f49f66d317266e33668)

For Temporal we allowed the 12 read tools (`list_*`, `describe_*`, `get_*`, `count_*` and `query_workflow`) and set the 19 write tools, such as `start_workflow`, `signal_workflow` and `terminate_workflow`, to **Needs Approval**. In Claude Desktop that shows an approval card before each write runs.

## Step 9: Users connect it

Each employee turns the server on once:

1. In Barndoor, open **My Apps**.
2. Find the server, for example **Temporal (local)**, and select **Connect**.
3. If the release has per-user credentials, enter them. Optional fields can stay blank.

Bridge picks it up on its next sync, about every five minutes, or right away with `barndoor sync`. A Claude Desktop session that was already open keeps the servers it started with; launch a new one from Bridge.

### Servers that need a one-time sign-in

Some servers keep their own sign-in instead of taking a credential from Barndoor. Auth0's server, for example, has an `init` command: a browser sign-in that saves a token in the macOS keychain, which the server reads on every start. Upstream you'd run `npx @auth0/auth0-mcp-server init`, but that needs Node and saves the keychain item for a different program.

Instead, the publisher lists the setup subcommands when signing, and each user runs them through the same signed build:

```bash theme={null}
# publisher, when signing
barndoor local-mcp sign … --setup-command init --setup-command session

# each user, once, after connecting the server
barndoor local-mcp exec auth0 init --read-only
barndoor local-mcp exec auth0 session   # check the sign-in
```

* `exec` runs only a first argument the signed release lists. It can't start the server itself, and a release without setup commands refuses every `exec` with `lists no setup commands`.
* It applies a governed launch's checks (signature, pinned key, sha256) and gives the command only the allowed environment plus the user's credentials. It runs in the build's cache folder, so a `.env` in your current folder isn't read.
* Run it in Terminal, not inside a Bridge session: `exec` refuses to run inside a governed session.
* Each run is recorded in your organization's audit log as a tool call on the server, without flag values or output. If the command fails, `exec` exits with, for example, `auth0 init exited with status 1; its output is above`.
* Auth0's `init` also adds an entry for itself to one client's MCP settings (`--client`, default `claude`). Bridge ignores that entry; remove it if that client also runs outside Bridge.

> [!WARNING]
>
> **Setup commands need newer software everywhere.**
>
> * **Platform:** Barndoor's platform accepts releases with setup commands from platform v2.54.0. On an older platform, `publish` rejects them.
> * **Macs:** `--setup-command` raises the release's minimum CLI to 0.1.281. Older CLIs don't just skip such a release: they fail their whole sync. Publish one only after every Mac in your organization runs Bridge 0.1.218 or later.

## Step 10: Pin the key with MDM

IT adds the `<dict>` that `keygen` printed to the `publisher_keys` array of the **Barndoor CLI — Managed Settings** profile (payload `ai.barndoor.cli`) you already deploy:

```xml theme={null}
<key>publisher_keys</key>
<array>
  <dict>
    <key>key_id</key><string>tenant:YOUR-ORGANIZATION-ID:release-2026</string>
    <key>public_key</key><string>BASE64_PUBLIC_KEY_FROM_KEYGEN</string>
    <key>allowed_hosts</key><array><string>releases.example.com</string></array>
  </dict>
</array>
```

* **Edit the profile you deploy today**; keep its other keys as they are. Rendering the profile again from the MDM kit gives it new UUIDs and can add keys your current profile doesn't have, such as `update_channel`, which would move Macs to a different update channel.
* **Version it.** This profile goes to every Mac running Bridge, so treat the change as a fleet change: name the new one "… v4", deploy it, and remove the old version only after the new one is installed.
* **Don't leave two copies deployed.** Two profiles with the same payload leave each Mac with whichever one the MDM applied last.
* Run `plutil -lint managed-prefs.mobileconfig` before uploading.
* Employees can't edit this profile, and neither can Barndoor.

### Rippling

Rippling can't edit an uploaded profile, so you upload the new version as a new policy:

1. **IT → Devices → Policies**. Under **Library**, open **macOS library**, then **Upload ▾ → Custom configuration profile**.
2. Name it, for example **Barndoor CLI — Managed Settings v4**, add a description, and choose platform **macOS**.
3. Upload the `.mobileconfig` **from a Mac**; Rippling silently fails uploads from other systems. The file picker hides folders whose names start with a dot, so copy the file somewhere like `~/Downloads` first.
4. In **Deploy policy**, choose who gets it. (For a policy that's already deployed, open it and select **Manage deployment** to get the same dialog.) The default, **Specific devices → Device → OS type is: macOS**, is every Mac. To target teams, choose **Applies to: Specific people → Membership rules**, and add a rule such as **Employee → Department** equals your departments. Select **Preview people** to check the list. New hires in those departments join automatically.

   ![Rippling's Deploy policy dialog: Applies to Specific people, with the membership rule Employee → Department equals Engineering, Product, Solutions Engineering, an empty Except field, and View applied rules and Preview people buttons](https://mintcdn.com/barndoor/72VeZGR96UrrQTrS/images/barndoor-bridge/rippling-deploy-department-rule.png?fit=max\&auto=format\&n=72VeZGR96UrrQTrS\&q=85\&s=eeb39500a5dd27cfc77a9322a4f943be)

   If the **Department** options under **Specific devices** are greyed out with "You don't have permission to use this field", use **Specific people** as above, or ask a Rippling admin with access to Department.
5. Deploy. Wait for it to show as installed, then retire the old version under **My policies → Everything else**.

Expect `/Library/Managed Preferences/ai.barndoor.cli.plist` to disappear for a few seconds on each Mac while Rippling swaps profiles. Macs dropped from the targeting lose the whole profile, including `org_hint` and `updates_managed`, so check that every Mac running Bridge is still covered.

### Iru, Jamf Pro and Intune

The change is the same in any Apple MDM: replace the Barndoor CLI — Managed Settings custom profile with the version that has `publisher_keys`, scoped to the same Macs.

* **Iru (Kandji):** **Library → Custom Profile**, assigned through the Blueprints your Bridge Macs are in.
* **Jamf Pro:** **Computers → Configuration Profiles → Upload**, scoped to your Bridge smart or static group.
* **Microsoft Intune:** **Devices → macOS → Configuration → Create → New policy → Templates → Custom**, assigned to your Bridge device group.

See [Install with MDM](https://docs.barndoor.ai/how-tos/barndoor-bridge/install-with-mdm) for how this profile fits with the rest of the Bridge deployment.

## Step 11: Verify on a Mac

**In the Bridge window,** open the **Servers** tab. It lists every synced server with a status, blocked servers first. When something won't run, the **Status** tab says how many next to the server count, for example **1 needs attention**, and links to it.

| Servers tab shows | Meaning |
| - | - |
| **Ready** | Verified. With "Downloads the first time it is used.", the build hasn't been downloaded yet. |
| **Blocked** | Won't run. The line under it says what to do, such as "Ask IT to add your organization's publisher key to the Barndoor MDM profile." |
| **Local approval only** | Approved with `barndoor local-mcp trust` on this Mac, which Bridge ignores. Publish it with your organization's key. |

**In Terminal,** `barndoor doctor` shows whether the key is pinned. Each pinned key is listed under **Tenant publisher keys (MDM)**, and the fingerprint must match the one `keygen` printed. A malformed entry is skipped, and `doctor` says why under the same heading.

![Terminal output of barndoor doctor: Managed preferences (MDM) present with keys updates\_managed, org\_hint and publisher\_keys, and under Tenant publisher keys (MDM) one tenant key with fingerprint=3d09701b and hosts=storage.googleapis.com](https://mintcdn.com/barndoor/72VeZGR96UrrQTrS/images/barndoor-bridge/local-mcp-doctor-publisher-keys.png?fit=max\&auto=format\&n=72VeZGR96UrrQTrS\&q=85\&s=899a0079679b0b3d1d79cdd7b9c343c3)

Run `barndoor sync`, then `barndoor list`, to see each local server's state:

![Terminal output of barndoor list showing auth0 as managed\_local\_mcp 10 tools (v0.1.19 verified, downloaded) and temporal as managed\_local\_mcp 31 tools (v1.12.0 verified, downloaded)](https://mintcdn.com/barndoor/72VeZGR96UrrQTrS/images/barndoor-bridge/local-mcp-list-verified.png?fit=max\&auto=format\&n=72VeZGR96UrrQTrS\&q=85\&s=36938d0ec5c320361b6de09109fc9b45)

| `barndoor list` shows | Meaning |
| - | - |
| `(v1.12.0 verified, not downloaded)` | Signature and key check out. The build downloads on first use. |
| `(v1.12.0 verified, downloaded)` | Ready. The cached build matches the signed sha256. |
| `(failed: key not pinned for this organization)` | This Mac's MDM profile doesn't pin the key, or pins it for a different organization. |
| `(failed: host not allowed for key)` | A download URL uses a host missing from the key's `allowed_hosts`. |
| `(failed: unrecognized signing key)` | The release's `key_id` isn't a key this Mac knows. Sign with a key from `keygen`, or update Bridge. |
| `(failed: requires CLI 0.1.281 (running …))` | Bridge on this Mac is older than the release allows. Update Bridge. |
| `(failed: no build for darwin/amd64)` | The release has no build for this Mac's architecture. |
| Not listed | The user hasn't connected it, the installation is off, or the Mac hasn't synced. `barndoor sync` reports `… N managed local MCP …`. |

**Does it work?** In a new Bridge session (or `barndoor run claude`), ask the agent to call one of the server's read tools.

## Troubleshooting

| You see | Cause | Fix |
| - | - | - |
| `This tool is blocked by policy.` on every tool | No policy grants the server's tools. | [Step 8](#step-8-set-a-policy-required). |
| `tool "<name>" on server "<slug>" is denied by policy` | That tool is **Off** for this user's groups. | Change the tool in the policy. |
| `failed: key not pinned for this organization`, or **Blocked** in the Servers tab | The MDM profile on this Mac doesn't have the key yet. | [Step 10](#step-10-pin-the-key-with-mdm). Check with `barndoor doctor`. |
| `failed: host not allowed for key` | The `--url-template` host isn't in the key's `allowed_hosts`. | Add the host to the MDM entry, or sign again with an allowed host. |
| `failed to start server "<slug>": managed server failed to start; last N lines of the server's stderr …` | The server exited while starting, most often because a credential, setting or sign-in is missing. The quoted lines are the server's own error; the full output is in `~/Library/Logs/Barndoor/local-mcp/<slug>.log`. | Fix what the server's message says: the user's credentials when connecting, the installation's configuration, or a [one-time sign-in](#servers-that-need-a-one-time-sign-in). |
| Connected, but the server isn't in the Servers tab or `barndoor list` | The Mac hasn't synced, or the installation is disabled. | `barndoor sync`; check the installation is enabled. |
| A Claude Desktop session doesn't have the server | That session started before the server synced. | Launch a new session from Bridge. |
| `package` fails naming a file and line | The npm server loads code from a path only known at runtime. | Patch that load by hand and [package by hand](#step-1-package-the-server), or ask the server's maintainers. |
| `must be a JSON array of {name, description, input_schema}` (sign) | A hand-written tools file uses raw MCP field names. | Use `package`'s `tools.json`, or convert it. |
| `credentialed servers cannot use ambient credentials for tool discovery` (sign) | `--credential-schema` without `--tools-from`. | Pass `--tools-from`. |
| `--version` refused (sign) | Not `X.Y.Z`. | `0.1.0-beta.19` → `0.1.19`. |
| `config key "…" is not declared by this catalog entry` (install) | A `--config` key the configuration schema doesn't have. | Use the keys it lists, or publish again with `--configuration-schema`. |
| `lists no setup commands` (exec) | The release wasn't signed with `--setup-command`. | Sign and publish with the setup commands the server needs. |
| Downloads fail from GitHub releases or a signed-in host | Bridge doesn't follow redirects to other hosts and doesn't sign in. | Host the builds on a public HTTPS host with no redirect. |
| You lost the signing key | The seed wasn't in a secret store. | Generate a new key, pin it with MDM, sign and publish again, then remove the old key from the profile. |

## Worked example: Temporal end to end

This is the run we did on Barndoor's own organization, condensed. The builds are at `storage.googleapis.com/barndoor-local-mcp-examples`.

**1. Package**

```bash theme={null}
barndoor local-mcp package pypi:temporal-mcp-server==1.12.0 --out pkg/temporal --name temporal-mcp
```

About 50 seconds for both architectures, with no manual patches. Both builds listed 31 tools. Against a local Temporal dev server, `list_workflows` answered `Showing all 0 workflows (skipped 0). No more results.`

**2. Key, sign**

```bash theme={null}
barndoor local-mcp keygen --name walkthrough-2026-11b --allowed-host storage.googleapis.com --out ./publisher-key
barndoor local-mcp sign \
  darwin/arm64=pkg/temporal/darwin-arm64/temporal-mcp darwin/amd64=pkg/temporal/darwin-amd64/temporal-mcp \
  --ref-name temporal --version 1.12.0 \
  --url-template 'https://storage.googleapis.com/barndoor-local-mcp-examples/temporal/{version}/{platform}/{executable}' \
  --key ./publisher-key \
  --args=--host --args='{{config.host}}' --args=--namespace --args='{{config.namespace}}' \
  --env-allowlist PATH,HOME --tools-from pkg/temporal/tools.json --credential-schema temporal-credentials.json \
  --out signed/temporal-1.12.0
```

The key's fingerprint was `3d09701b`. Its seed went straight into a cloud secret manager.

**3. Upload, publish, install**

```bash theme={null}
gcloud storage cp pkg/temporal/darwin-arm64/temporal-mcp gs://barndoor-local-mcp-examples/temporal/1.12.0/darwin-arm64/temporal-mcp
gcloud storage cp pkg/temporal/darwin-amd64/temporal-mcp gs://barndoor-local-mcp-examples/temporal/1.12.0/darwin-amd64/temporal-mcp
barndoor local-mcp publish signed/temporal-1.12.0 --name "Temporal (local)" --description "…" \
  --configuration-schema temporal-config-schema.json
barndoor local-mcp install temporal --config host=localhost:7233 --config namespace=default
```

`Published com.barndoor.tenant.….temporal 1.12.0 as "temporal" (catalog id …, 31 tools).`, then `Installed (created) temporal.` with `availability: opt_in`.

**4. Connect**

Connected **Temporal (local)** from **My Apps**. `barndoor sync` reported `Synced 35 servers (16 remote, 18 embedded, 1 managed local MCP, 0 unsupported)`, but the key wasn't pinned yet:

```text theme={null}
temporal             managed_local_mcp 31 tools (failed: key not pinned for this organization)
```

**5. Pin the key**

Uploaded **Barndoor CLI — Managed Settings v4** in Rippling with the `publisher_keys` entry, targeted with **Employee → Department** equals Engineering, Product and Solutions Engineering (15 people in **Preview people**), then retired v3. `barndoor doctor` showed `fingerprint=3d09701b  hosts=storage.googleapis.com`, and `barndoor list` changed to `(v1.12.0 verified, not downloaded)`.

**6. Set the policy**

Before the policy, a governed Claude Code session got `This tool is blocked by policy.` on every Temporal tool. We added one policy for all users: the 12 read tools **Always Allow**, the 19 write tools **Needs Approval**. With no restart, we asked Claude Code (`barndoor run claude`) to list workflows and describe one. It answered `Workflow count: 1 · type BarndoorSmokeWorkflow · status WORKFLOW_EXECUTION_STATUS_RUNNING` in 17 seconds, including Bridge downloading and verifying the build on first use. `barndoor list` then showed `(v1.12.0 verified, downloaded)`.

**7. Use it from every client**

Codex CLI through Barndoor listed the same workflow. In Claude Desktop launched from Bridge, reads ran directly, and `start_workflow` showed an approval card and ran after approval.

> [!NOTE]
>
> Auth0 went through the same steps and verifies on every pinned Mac, but its tools need an Auth0 sign-in. Without one, a call fails to start the server, and the error quotes Auth0's own message: `Authorization Error: No valid authorization token found`. A user can enter their Auth0 domain and a Management API token when connecting (the credential fields we signed), but those tokens expire after 24 hours by default. The better fit is Auth0's own sign-in: sign the release with `--setup-command init`, and each user runs `barndoor local-mcp exec auth0 init --read-only` once (see [Servers that need a one-time sign-in](#servers-that-need-a-one-time-sign-in)).

## Ship a new version

Package, sign with a new `--version` (and the same `--ref-name`), upload to the new URLs, and publish. Installations, policies and user connections carry over, and Macs download the new build on their next session. In CI, run `install` after `publish` too if you want the pipeline to own the installation's configuration.

Republishing the same version is allowed, for example after re-packaging or moving the builds. Remember that the download URL is signed: moving the files means signing again.

## Turn it off

* **Disable:** `barndoor local-mcp install <slug> --disabled`, or turn off **Enabled** on the installation in the admin UI. It stops on every Mac at the next sync.
* **Remove from catalog:** from the entry's card menu in the admin UI. It removes every installation of it too.
* **Revoke a key:** remove its entry from `publisher_keys` in the MDM profile. Macs stop trusting everything signed with it as soon as the profile updates.
* **Rotate a key:** generate a new key, pin it next to the old one, sign and publish with the new key, then remove the old key from the profile.

## Current limitations

* Builds must be downloadable without signing in. Private buckets and token-protected artifact servers aren't supported.
* Each platform's build must be one self-contained file, started over stdio. `package` builds Mac executables, on a Mac.
* Policies are set in the admin UI.
* Setup commands need platform v2.54.0 or later and Bridge 0.1.218 or later on every Mac.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.