<div align="center">
  <img src="assets/brand/agentomy-logo-dark.svg" alt="Agentomy" width="320" />
</div>

# Agentomy MCP Gateway

<sub>An open piece of **[Agentomy](https://agentomy.com)**, the governance layer for AI agents in regulated enterprises. See the others at [github.com/getagentomy](https://github.com/getagentomy).</sub>

![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg) ![focus](https://img.shields.io/badge/focus-MCP%20governance-blue)

Governs **any** stdio MCP server by sitting between the agent and the server. Every
`tools/call` is checked against your policy before it reaches the server. A refusal is
answered by the gateway and never forwarded, so the side effect does not happen.

Nothing about the upstream server changes. It is not patched, not forked, and never
learns it is being governed.

## Why interpose instead of observe

A sidecar that watches MCP traffic and reports on it produces a record of the things it
failed to stop. Sitting on the wire is what turns a report into a refusal.

## Install and run

Install once with `npm install -g agentomy-mcp-gateway`, or run it on demand with `npx agentomy-mcp-gateway`.

```bash
# Instead of launching the MCP server directly:
#   my-mcp-server --flag
# launch it through the gateway:
AGENTOMY_ENDPOINT=https://your-agentomy \
AGENTOMY_API_KEY=... \
  agentomy-mcp-gateway, my-mcp-server --flag
```

In an agent's MCP configuration, replace the server's `command` and `args`:

```jsonc
{
  "mcpServers": {
    "dev-tools": {
      "command": "agentomy-mcp-gateway",
      "args": ["--", "the-original-command", "--its", "--flags"],
      "env": { "AGENTOMY_ENDPOINT": "https://your-agentomy", "AGENTOMY_API_KEY": "..." }
    }
  }
}
```

That is the whole integration. One config change, per agent, by the operator.

| Variable | Required | Meaning |
|---|---|---|
| `AGENTOMY_ENDPOINT` | yes | Platform base URL |
| `AGENTOMY_API_KEY` | no | Bearer token |
| `AGENTOMY_AGENT_ID` | no | Identity on the decision, default `mcp-gateway` |
| `AGENTOMY_TIMEOUT_MS` | no | Decision timeout, default `5000` |

## What it does to the protocol

| Message | Behaviour |
|---|---|
| `tools/call`, permitted | Forwarded unchanged |
| `tools/call`, refused | **Not forwarded.** JSON-RPC error `-32000` on the same id, with `data.governed = true` and the reason |
| `tools/call`, refused, no id | Dropped. A notification must never be answered, so the call is stopped and the reply withheld |
| Everything else | Forwarded unchanged |
| Upstream to agent | Forwarded verbatim. Results are not rewritten |

Requests are adjudicated in arrival order. Deciding concurrently would let a later call
reach the server before an earlier one was resolved, which is a reordering bug that only
shows up under load.

## Fail-closed, and what that costs you

Every failure path denies:

| Condition | Reason returned |
|---|---|
| Endpoint unreachable | `governance_unreachable` |
| Decision timed out | `governance_timeout` |
| Non-2xx response | `governance_http_error` |
| Body not JSON, or no boolean `authorized` field | `governance_malformed_response` |
| Fleet halted | `agent_halted` |
| Policy refused | `policy_denied` |

The honest trade: **if the platform is down, governed tools stop working.** That is the
correct behaviour for a governance component and it is a real availability coupling. Run
the platform accordingly.

The reasons are distinct on purpose. An operator seeing `governance_unreachable` has an
outage; one seeing `policy_denied` has a policy question. Collapsing them into "denied"
would make the two indistinguishable at exactly the moment the difference matters.

A missing `authorized` field denies rather than being read for truthiness, because a
truthiness check turns any unexpected payload, including an error object, into an allow.

## What it does not do

It governs actions, not discovery. `tools/list` passes through. Narrowing what an agent
may *see* while leaving what it may *do* ungoverned would be theatre in the wrong place.

It does not rewrite results. The gateway adjudicates requests; making it edit responses
would turn it into a participant in the conversation rather than a gate on it.

It does not inspect arguments semantically. Policy receives the tool name and the
argument *keys*, not the values. Argument-level policy is a platform concern and sending
full argument values to a decision endpoint would put file contents and shell commands
into a second system.

## Licence

Apache-2.0.