Archytan Lite MCP gate

archytan-mcp-gate

archytan-mcp-gate sits between an MCP host (Claude Code, Claude Desktop, an IDE agent, your own agent) and an MCP tool server. Before any tool call reaches the server, an Archytan Lite gate service has to authorize it. The MCP gate checks the signed receipt for that decision and spends a single-use capability, and only then forwards the call. A call the policy doesn't allow comes back to the agent as a tool error it can read, and never reaches the server.

This repository is the MCP gate's source, under the Apache License 2.0. The Archytan Lite gate service it talks to is a separate product, distributed as a signed container image; its quickstart is in archytan-lite-community.

How it works

The host launches the MCP gate in place of the tool server, and the MCP gate launches the server itself, so it becomes the only path between the agent and its tools. For every tools/call it:

1. asks the Archytan Lite gate service to authorize the action the call maps to, on the resource the call names;
2. verifies the receipt the service returns: its fields must hash to the signed intent hash, the signature must be the service's key, and the receipt must describe exactly this call;
3. redeems the single-use capability that came with the ALLOW;
4. forwards the call to the tool server.

If any step fails, the call is refused and the server never sees it. The agent never holds anything that could skip these steps: the MCP gate holds the agent's credential, and the agent only ever speaks MCP.

Requirements

• An Archytan Lite gate service with capabilities on (ARCHYTAN_LITE_CAPABILITIES=on). The tests run against version 2.7.0, the first whose policy can scope a role to named resources.
• A credential-bound caller for the agent, made with the service's callergen. The MCP gate never sends a role; the agent's role is whatever its credential holds.

Install

Download the binary for your platform from this repository's releases. SHA256SUMS covers every binary and is signed by the workflow that built them, with cosign keyless signing:

cosign verify-blob SHA256SUMS --bundle SHA256SUMS.cosign.bundle \

--certificate-identity-regexp '^https://github.com/High-ArchyTech-Solutions/archytan-mcp-gate/\.github/workflows/release\.yml@refs/tags/v' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com sha256sum -c SHA256SUMS --ignore-missing

Or build it yourself with Go:

go install github.com/high-archytech-solutions/archytan-mcp-gate/v2/cmd/archytan-mcp-gate@latest

Each release also attaches archytan-mcp-gate.mcpb, an MCP bundle for hosts that install them, and lists it in the MCP Registry as io.github.High-ArchyTech-Solutions/archytan-mcp-gate. The host asks for four things: an mcp-gate.json that names the tool server in its server field (see Configure), the gate service's URL, the agent's token file and the service's public key. The bundle carries the builds for macOS and Linux on amd64 and arm64, and for Windows on amd64, which Windows on Arm runs under emulation. SHA256SUMS covers it too. The macOS builds aren't notarized by Apple, so macOS may refuse to run one that arrived through a browser until you clear its quarantine (xattr -d com.apple.quarantine ).

Configure

Map each tool you want the agent to have to a policy action in mcp-gate.json. resource_id_arg names the argument that identifies the resource the call acts on:

{

"version": 1, "agent_uid": "agent-invoices", "tools": { "delete_invoice": { "action": "invoice.delete", "resource_type": "invoice", "resource_id_arg": "invoice_id" }, "read_invoice": { "action": "invoice.read", "resource_type": "invoice", "resource_id_arg": "invoice_id" } } }

Then point the host at the MCP gate instead of the tool server. The same mcpServers entry works in Claude Desktop's claude_desktop_config.json and a project's .mcp.json:

{

"mcpServers": { "invoices": { "command": "archytan-mcp-gate", "args": ["--config", "/etc/archytan/mcp-gate.json", "--", "node", "/opt/invoice-server/index.js"], "env": { "ARCHYTAN_MCP_GATE_URL": "https://gate.internal:8421", "ARCHYTAN_MCP_GATE_CALLER_TOKEN_PATH": "/etc/archytan/agent-invoices.token", "ARCHYTAN_MCP_GATE_PUBLIC_KEY_HEX": " " } } } }

The tool server can be named in mcp-gate.json instead of after --, which suits a host or bundle that only lets you pass a config file:

{

"version": 1, "agent_uid": "agent-invoices", "server": { "command": "node", "args": ["/opt/invoice-server/index.js"] }, "tools": { "read_invoice": { "action": "invoice.read", "resource_type": "invoice", "resource_id_arg": "invoice_id" } } }

The host's entry is then "args": ["--config", "/etc/archytan/mcp-gate.json"]. The command runs exactly as written and inherits the MCP gate's environment, the same as after --. Name the server in one place: with a server in the config and a command after --, the MCP gate refuses to start rather than pick one.

mcp-gate.json is read as strictly as host messages are. An unknown field, a key that repeats or differs only in case at any depth, and text that isn't valid UTF-8 or escapes an unpaired surrogate all stop the MCP gate at startup, so a second server can't quietly decide which program runs.

A resource named by several arguments

Some tool servers name the resource a call acts on with more than one argument. GitHub's MCP server takes owner and repo separately, and its write tools add a branch. List them in resource_id_args instead of resource_id_arg, and the MCP gate joins their values with / into the resource id it sends:

"get_file_contents": { "action": "repo.read", "resource_type": "repo", "resource_id_args": ["owner", "repo"] },

"push_files": { "action": "repo.push", "resource_type": "repo_branch", "resource_id_args": ["owner", "repo"], "resource_id_path_arg": "branch" }

A push_files call with owner acme, repo web-shop and branch feature/login is authorized as acme/web-shop/feature/login. With Archytan Lite 2.7.0's grants, the policy can then scope the agent's role:

{ "action": "repo.read", "grants": [{ "roles": ["repo_agent"], "resource_ids": ["acme/web-*"] }] },

{ "action": "repo.push", "grants": [{ "roles": ["repo_agent"], "resource_ids": ["acme/web-*/feature/**"] }] }

The agent can read the acme/web-* repositories and push to their feature/ branches. A push to main, or to another owner's repository, is refused.

• Each resource_id_args value must be a single name. A value containing / or \ is refused, because joined with the others it would name a different resource: owner a/b with repo c reads the same as owner a with repo b/c, and only the MCP gate knows which argument a segment came from.
• resource_id_path_arg is joined last and may span several segments, like a branch name. There's at most one, since two values with separators in them could be split more than one way.
• Every listed argument must be there as a non-empty string. A missing one is refused, never left out of the id: a tool that fills in a default, such as the default branch, would act on a resource the id doesn't name. Numbers and other types are refused too.
• The joined id is then Archytan Lite's to judge. Under a rule scoped by resource it refuses .., empty segments and characters outside its grammar before any grant is matched, so feature/../main doesn't reach main.
• Write patterns in the tool's own casing. Lite compares exact bytes and a grant only allows, so a variant such as ACME/web-shop is refused.

Scope each tool at the level its id actually names. An argument left out of the id doesn't narrow anything: push_files takes a files array, so scope it by repository and branch, never by file path, and get_file_contents takes an optional ref and a sha that overrides it, so scope reads by repository. Branch scoping covers only the tools that take a branch; merging a pull request into main is merge_pull_request, which names a pull request number, so give it an action of its own.

An MCP gate older than 2.8.0 refuses to start with a config that uses resource_id_args, rather than ignore it.

What it does on the wire

• Tools the policy doesn't cover are hidden and refused. tools/list shows the agent only mapped tools, and a call to any other name is refused without reaching the service or the server. resources/*, prompts/*, completion/*, tasks/* and unknown methods are refused, and those capabilities are removed from what the server advertises.
• The host can't widen the server's scope. MCP roots let a host tell a server which folders to work in, and servers that honour them (the reference filesystem server, for one) swap their configured folders for the host's list. Behind the MCP gate, the folders you give the server in its command are the ones it keeps: the gate removes roots from what the host declares, answers or refuses a server's request for roots, and drops roots change notifications.
• Both protocol generations pass. The MCP gate relays the initialize handshake and MCP 2026-07-28: server/discover, requests that carry their own capabilities, input_required round trips for elicitation and sampling, and subscriptions/listen, narrowed to tool list changes. Each round of a call that stops to ask the user something is authorized and spent on its own, since each is a call the server may act on.
• A message that reads two ways is refused. JSON parsers disagree on an object whose keys repeat or differ only in case, and on text that isn't valid UTF-8 or escapes an unpaired surrogate. A host message like that is refused before anything is authorized or forwarded, so the MCP gate and the server always agree on the call that was decided.
• Refusals read as tool results. A refused call comes back as a tool result with isError set and a plain explanation the model can act on.
• The agent's trace reaches the decision. A W3C traceparent in a tool call's params._meta is passed to the service, so its log lines and version 2 receipt carry the agent's trace id. Trace context never changes a decision.
• Calls run in the order the agent issued them, while pings, notifications and cancellations are never held up behind them.
• Cancellation is honoured at every step. Cancelled before the capability is redeemed: nothing is spent or executed. Cancelled after forwarding: the cancellation is relayed to the server, the only party that can still stop it.
• The tool server doesn't outlive the MCP gate. When the gate exits it closes the server's input, then asks the server to stop, then forces it. On Windows the server also runs in a job object, so i