MCP Manager

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

How Authsia rewrites MCP config

Authsia never silent-rewrites a client file. MCP Manager Protect connection / Protect a client and authsia mcp wrap --write show the current entry, the replacement, and a SHA256 checksum. You confirm; --yes or the native sheet applies the write. authsia mcp configure prints a user-global fallback and does not write.

The coding tool’s launch is replaced so it starts Authsia. The real child command is declared in workspace policy. For the recognized npx @modelcontextprotocol/server-filesystem launch, the selected managed workspace replaces all previous directory arguments as the server’s single exposed root. The confirmation names this scope; other packages and ambiguous argument forms keep their original arguments. Protect or re-protect also updates an existing filesystem declaration after native confirmation, preserving tool policy, credential bindings, and the catalog. Removing protection retains that declaration; upgrades do not widen its scope automatically. A Cursor project wrap looks like this (from an Authsia-Demo workspace Protect of codegraph):

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

{
  "mcpServers": {
    "codegraph": {
      "command": "/Applications/Authsia.app/Contents/Helpers/authsia",
      "args": ["mcp", "proxy"],
      "env": {
        "AUTHSIA_MCP_LAUNCH": "[\"codegraph\",\"codegraph\",\"serve\",\"--mcp\"]",
        "AUTHSIA_MCP_UPSTREAM": "codegraph",
        "WORKSPACE_FOLDER_PATHS": "/Users/you/PlayGround/Authsia-Demo"
      }
    }
  }
}

The child is declared in that workspace’s .authsia/workspace.json. Neighboring servers stay. Wrap does not copy client-side environment values; the preview names how many there were. Secret refs stay in workspace policy as authsia://.

{
  "mcpUpstreams": [
    {
      "name": "codegraph",
      "command": "codegraph",
      "args": ["serve", "--mcp"],
      "transport": "stdio"
    }
  ]
}

Global connections, workspace-specific protection

A global client entry makes a server available across projects. Each Authsia workspace still decides how that server runs.

The Servers table shows each effective client’s protection status next to its name — including mixed protected, bypassing, and unconfigured connections.

Set up another workspace

1. Select and discover

   Choose the target workspace and discover its servers.

2. Use existing setup

   Open the already-wrapped server, pick the source workspace, and review launch plus tool policy.

3. Confirm

   Creates an independent declaration. Later edits are not synchronized.

4. Bind secrets and admit

   Add required secret bindings, reload the client, then make a permitted call.

Which workspace runs

Unresolved or ambiguous proxy workspace hints stop startup rather than selecting another project’s policy.

What it gates

Declare a no-shell stdio command or a validated loopback HTTP URL 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.

Allowlist Authsia in managed agent settings

Deploy two things: an administrator-enforced launch policy, and client configuration that connects through Authsia. Copying a user config file is not enforcement.

Five clients from authsia mcp configure on macOS. Vendor docs checked 8 Sep 2026 — validate the deployed client version.

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"] }
  ]
}

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" },
] }

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

VS Code with GitHub Copilot

VS Code 1.132+: deploy the Claude-shaped JSON through Copilot managed settings, or policies ChatAllowedMcpServers and ChatAllowManagedMcpServersOnly. Do not paste those names into ordinary workspace settings.

Devin Desktop

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

Print only — merge, do not replace unrelated settings. The fallback names the upstream only. A Cursor project Protect write also sets WORKSPACE_FOLDER_PATHS and AUTHSIA_MCP_LAUNCH; see How Authsia rewrites MCP config.

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

Before broad deployment, verify on a pilot Mac:

• Reload the client and confirm it received the managed policy. Check project entries as well as user-global entries.
• Confirm an approved proxy connection reaches Authsia admission and a permitted tool works after approval.
• Confirm a harmless direct MCP fixture is blocked by the client policy, including under an approved server name. A doctor finding alone is not proof of enforcement.
• Add another wrapped server: Claude, Cursor, and supported VS Code should accept the shared command; Codex needs that server name added to requirements.
• Run authsia mcp doctor from every target workspace, resolve effective direct launches, then confirm revocation stops an admitted STDIO child. Record redacted results only.

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

See How Authsia rewrites MCP config for the file-level before and after. Previews keep child env keys and replace every value.

If the scanned entry already set child environment, name tools under mcpUpstreams.tools.allow instead of automatic catalog recording.

Unwrap previews both entries plus checksum, then restores command and argv from that row’s workspace declaration. Old client env cannot be recovered. Reopen the client after restoring.

Catalog capture and policy review

Allow tools reuse admitted server access. Approve tools require native approval on every STDIO or HTTP invocation, even when the server is already running. A cold STDIO call may also ask for server admission or credential access. After upgrading Authsia, restart client MCP connections so the proxy and app both support per-call approval.

Deny tools are hidden from clients. Only calls received by Authsia appear as denied attempts; a chat request for an unavailable tool creates no MCP call record. Activity records policy changes separately. Open a configuration-change row to see the reviewed changes, such as edit_file: Allow → Deny, the recorded actor class (native, not caller identity), and time. Reviewed summaries preserve line breaks up to 4,000 characters. Approval and admission refusals are denied / approvalDenied; disabled CLI access is denied / cliAccessDisabled. A lost session is upstreamUnavailable, not a workspace-policy denial. Tool names in those summaries are searchable and included in the Activity metadata export.

Capture starts the child once behind admission and records metadata.

mcp doctor prints scanned launches plus a verdict. Exit 2 means an effective or conditional bypass. Unreadable client files are skipped.

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

MCP Manager and localhost HTTP

Optional upstream headers stay Keychain references and resolve after admission. Activity records server, tool, attribution, and coarse outcome — not payloads or credentials.

Access Center