MCP Manager

Gate workspace-declared local MCP servers through the existing STDIO proxy or the app-owned localhost Streamable HTTP manager. Credentials stay behind native admission and Keychain references.

Global connections, workspace-specific protection

A global client entry makes a server available across projects. Each Authsia workspace still decides how that server runs and which tools and secrets it may use.

For example, a global Playwright proxy entry can serve project-a and project-b, but both need their own Playwright declaration. If only project-a has one, Manager shows Playwright as unconfigured in project-b, and calls there are blocked until it is configured.

Set up another workspace in Manager

  1. Select the target workspace and discover its servers.
  2. Open the already-wrapped server and choose Use existing setup. Select the source workspace and review the launch and tool policy.
  3. Confirm in Authsia. This creates an independent declaration; future edits are not synchronized between workspaces.
  4. Add any required secret bindings in the target workspace, reload the client, and make a permitted call to request runtime admission.

Secret bindings, runtime grants, and recorded catalogs are not copied. Relative launch paths resolve in the target workspace. If no matching setup is available, use Manual setup to enter the original server command.

Which workspace is used? For STDIO, an explicit --workspace takes precedence; otherwise Authsia uses a safe WORKSPACE_FOLDER_PATHS hint, then the proxy process's working directory. Changing the workspace filter in Manager does not switch a running client's workspace.

HTTP is different: a protected HTTP endpoint and its enrolled association belong to a specific workspace and server. Configure and enroll the target workspace's HTTP server separately; the endpoint does not switch policies when the client changes directories.

What it gates

Declare a no-shell stdio command or a validated loopback HTTP URL, optional authsia:// references, and optional tool allow/approve/deny names in the commit-safe workspace file. STDIO clients launch authsia mcp proxy; HTTP clients use the manager’s protected endpoint. Authsia starts or forwards only after approval.

Enable MCP Integrations in Settings > Developer Access first. Client configuration cannot turn this on.

MCP setup and launch commands (configure, wrap, unwrap, declare, catalog, serve, proxy, start, and restart) fail while MCP Integrations is off. Enable MCP Integrations in Authsia Settings > Developer Access, then retry. The CLI never changes the toggle. Help, status, doctor, activity export, stop, and portal revocation remain available for inspection and cleanup.

Allowlist Authsia in managed agent settings

Deploy two things: an administrator-enforced policy that restricts MCP launches, and client configuration that connects through Authsia. Copying a user configuration file alone does not enforce company policy. This guide covers the five clients supported by authsia mcp configure on macOS. Vendor policy documentation checked September 8, 2026; validate the deployed client version before rollout.

Install the signed Authsia app at a company-controlled path and enable MCP Integrations in Settings > Developer Access. The examples assume /Applications/Authsia.app/Contents/Helpers/authsia; replace it everywhere if your fleet uses another path. Declare each upstream and its tool/secret policy in the target workspace's .authsia/workspace.json.

The standard client launch uses mcp proxy with AUTHSIA_MCP_UPSTREAM naming the declaration. Keep --upstream and fixed workspace arguments out of these shared launches. The child command stays in Authsia workspace policy. Allow mcp serve too when exposing Authsia's own MCP tools. These launch policies do not approve an upstream or replace native admission.

Claude Code

Deploy this JSON through managed settings, for example MDM installing /Library/Application Support/ClaudeCode/managed-settings.json:

{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverCommand": ["/Applications/Authsia.app/Contents/Helpers/authsia", "mcp", "serve"] },
    { "serverCommand": ["/Applications/Authsia.app/Contents/Helpers/authsia", "mcp", "proxy"] }
  ]
}

Exact command matching lets users add new proxy server names without changing this allowlist. The managed-only flag prevents user allowlists from broadening it. Avoid name-only rules; deny rules still win. Deploy an exclusive managed-mcp.json only if IT intends to own a fixed server catalog: it prevents users from adding new wrapped entries. See Claude Code managed MCP controls and managed file locations.

Codex

Deploy requirements through /etc/codex/requirements.toml, cloud-managed requirements, or the macOS MDM preference com.openai.codex:requirements_toml_base64. Use a client supporting structured command matchers. This example approves the configured names authsia and jira:

[mcp_servers.authsia.identity]
command = { executable = "/Applications/Authsia.app/Contents/Helpers/authsia", args = [
  { match = "exact", value = "mcp" },
  { match = "exact", value = "serve" },
] }

[mcp_servers.jira.identity]
command = { executable = "/Applications/Authsia.app/Contents/Helpers/authsia", args = [
  { match = "exact", value = "mcp" },
  { match = "exact", value = "proxy" },
] }

Both the configured server name and identity must match. Replace jira with the generated name and repeat its block for each additional proxy entry. A two-entry policy does not cover arbitrary future names. Structured matchers check executable, argument count, and order; string-only identity.command does not restrict arguments. Neither checks environment or working directory. See Codex configuration reference.

Requirements restrict availability; they do not install connections. Put generated launches in ~/.codex/config.toml. Managed defaults alone are insufficient enforcement. Review plugin-bundled MCP separately through plugins.<plugin>.mcp_servers; for a rollout using only direct configuration, features.plugins = false in requirements disables plugins. See Codex managed configuration.

Cursor Enterprise

In the team dashboard's MCP Configuration, add these two command entries:

/Applications/Authsia.app/Contents/Helpers/authsia mcp serve
/Applications/Authsia.app/Contents/Helpers/authsia mcp proxy

Cursor matches the full command plus arguments. Use the exact deployed path rather than a broad wildcard. Disable permission for user MCPs outside admin-defined command/URL patterns when requiring Authsia-only launches. Set per-server tool and network controls for your upstreams, and pilot native Bridge connectivity under the selected sandbox mode. The allowlist does not install servers: distribute generated entries to ~/.cursor/mcp.json or the project .cursor/mcp.json. See Cursor enterprise MCP controls and user MCP extensions.

permissions.json / mcpAllowlist controls tool auto-run approval; it is not a substitute for the enterprise server launch policy. See Cursor permissions reference.

VS Code with GitHub Copilot

For VS Code 1.132 or later, deploy the Claude-shaped JSON above through Copilot managed settings: allowedMcpServers with the two exact serverCommand entries and allowManagedMcpServersOnly: true. Alternatively, deliver equivalent values through VS Code enterprise policies ChatAllowedMcpServers and ChatAllowManagedMcpServersOnly. Do not paste these policy names into ordinary workspace settings.

Individual allow/deny policies require 1.130; managed-only enforcement requires 1.132. Copilot managed allowlists replace the equivalent device policy, so keep delivery channels consistent. Leave ChatMCP at all for this manually configured pattern; none disables MCP, while registry requires a separate approved-registry deployment. Distribute connections into the user-profile mcp.json or project .vscode/mcp.json, using Authsia's VS Code output with its servers map. Verify applied policy with Developer: Policy Diagnostics. See VS Code enterprise AI settings.

Devin Desktop

Authsia generates local connections for ~/.config/devin/mcp_config.json with authsia mcp configure --client devin. Distribute that configuration and check it for drift. We have not verified a documented Devin Desktop administrator-enforced command allowlist equivalent to the controls above. Treat this as configuration distribution and detection, not proven prevention of direct launches. Confirm enforcement options with your vendor before using Devin Desktop for a mandatory Authsia-only deployment; cloud Devin MCP settings do not establish local Desktop enforcement.

Distribute connections and verify the rollout

From each declared workspace, print the matching client configuration:

authsia mcp configure --client claude
authsia mcp configure --client codex
authsia mcp configure --client cursor
authsia mcp configure --client vscode
authsia mcp configure --client devin

Use only the output for the installed client. This prints configuration; it does not deploy company policy. Claude uses ~/.claude.json, Codex and Cursor use the paths above, Devin uses its local config, and VS Code uses its profile's mcp.json. Merge entries rather than replacing unrelated settings. A typical Claude/Cursor proxy connection looks like this; jira must already be declared in that workspace:

{
  "mcpServers": {
    "jira": {
      "command": "/Applications/Authsia.app/Contents/Helpers/authsia",
      "args": ["mcp", "proxy"],
      "env": { "AUTHSIA_MCP_UPSTREAM": "jira" }
    }
  }
}

Before broad deployment, verify on a pilot Mac:

These examples permit STDIO connections only. For Authsia's protected localhost HTTP flow, separately approve the exact enrolled http://127.0.0.1:8788/mcp/{server-id} URL using the client's URL policy, and retain Manager-issued authentication. Do not allow the original upstream URL or every loopback endpoint. Remote MCP remains a separate company-gateway decision. Authsia gates traffic routed through it; client MCP policy does not enforce OS-wide process restrictions or make editable workspace declarations centrally immutable.

Print proxy entries

From a managed workspace, authsia mcp configure prints declared upstreams as separate proxy entries. A wrapped entry is declared and routed through Authsia, not pre-approved.

Declare an upstream

If a STDIO proxy launch has no workspace policy yet, declare the child command first. For a validated loopback HTTP endpoint, use --url under MCP Manager.

Wrap and unwrap

Wrap and Protect previews keep child env keys and replace every value. A scanned entry that already set child environment is not followed by automatic catalog recording — name tools under mcpUpstreams.tools.allow instead.

Remove protection previews the protected and restored entries plus their checksum before writing. It restores only from that row’s exact workspace declaration and leaves workspace policy in place. Client-side environment values from before protection cannot be recovered, and declared environment values — including authsia:// references — are not copied into the direct launch. Reopen the client after restoring it.

Catalog capture and policy review

Capture starts the child once behind admission and records metadata without changing permissions. New tools remain unreviewed and blocked until classified in MCP Manager Edit policy. Empty-policy calls do not discover or start servers.

Manager changes require a Bridge audit intent before applying. authsia audit export --verify includes their redacted intent/outcome records. The local Activity journal retains at most 30 days, 2,000 events, and 1 MiB and reports pruning; Activity rows do not imply HMAC verification.

mcp doctor prints a table of scanned launches plus a verdict. It exits 2 on an effective or conditional bypass. JSON is schema version 2 and includes host, user, Authsia version, MCP Integrations, and audit integrity. Unreadable or oversized client files are skipped and do not fail.

mcp activity export copies redacted proxy command-history rows. Filters: --since, --upstream, --workspace, --unowned.

MCP Manager and localhost HTTP

Run authsia mcp start from the signed Authsia app with MCP Integrations enabled. The portal binds to 127.0.0.1:8787. Protected local Streamable HTTP uses 127.0.0.1:8788/mcp/{server-id}. Stopping the manager ends HTTP forwarding and portal sessions; it leaves existing STDIO proxy processes and independently running HTTP servers running.

Discover servers scans supported client configs without starting them. Configure in Authsia prepares a declaration; Protect a client and HTTP enrollment write client config only after native confirmation. HTTP enrollment is limited to user-local Claude Code, Codex, and Cursor files; a conflicting project entry blocks enrollment.

Only explicit loopback HTTP endpoints are accepted (http plus localhost, 127.0.0.1, or ::1, and an explicit port). The first HTTP declaration advances that workspace to schema version 3, which older software rejects. Optional upstream headers remain Keychain references and are resolved after admission. Activity contains server, tool, attribution, and coarse outcome without raw protocol data or credentials.

Visibility boundary

Wrapped calls record the MCP tool name only — not arguments or results. A direct or unadmitted config entry is existence-only: Authsia cannot audit its calls, stop it on revoke, or prevent its launch. This local stdio and localhost HTTP layer complements a company MCP gateway’s SSO and remote policy; it does not replace the gateway.

Access Center

Grant revocation terminates the process group. On the MCP proxy tab, Access Center also lists recent proxy decisions that never created a grant — for example a denied or unavailable upstream. Those rows use the declared upstream name, honor the workspace filter, and sit in the same glass card treatment as grant rows. They are rejected before Authsia creates a grant.