writ proxy

Use writ proxy when Writ must be the MCP endpoint for a client. The proxy checks tools/call requests against the mcp grants in a writ file.

Use writ connect for Claude, Codex, Cursor, or OpenCode. That command uses native agent hooks and does not need an MCP proxy.

Write the MCP grant

writ: github-reader
mandate: "Read issues from the repository."

grants:
  - mcp: { tools: ["search_issues", "get_issue", "list_comments"] }

Enforce mode blocks a tool name that does not match the grant. An approval cannot widen the MCP grant. A configured organization policy can require approval for a tool that the MCP grant already permits.

Connect a local server

writ proxy github-reader.yaml -- npx -y @modelcontextprotocol/server-github

The MCP client starts Writ over standard input and output. Writ starts the command after -- and relays the protocol.

MCP client → Writ proxy → local MCP server
                  ↘ record

Example client configuration:

{
  "mcpServers": {
    "github": {
      "command": "writ",
      "args": [
        "proxy",
        "github-reader.yaml",
        "--",
        "npx",
        "-y",
        "@modelcontextprotocol/server-github"
      ]
    }
  }
}

Connect a remote server

Use a Streamable HTTP endpoint over HTTPS:

writ proxy github-reader.yaml --remote https://mcp.example.com/mcp

The client still connects to Writ over standard input and output. Writ relays the MCP session to the remote endpoint.

MCP client → Writ proxy → HTTPS → remote MCP server
                  ↘ record

Read a bearer token from an environment variable:

export MCP_ACCESS_TOKEN='...'
writ proxy github-reader.yaml \
  --remote https://mcp.example.com/mcp \
  --token-env MCP_ACCESS_TOKEN

Read another HTTP header from an environment variable:

export MCP_TENANT='team-42'
writ proxy github-reader.yaml \
  --remote https://mcp.example.com/mcp \
  --header-env X-Tenant=MCP_TENANT

Writ reads secret values at runtime. The command line and record contain the environment variable names, not their values. Redirects must keep the same origin. Remote production endpoints must use HTTPS.

Flags

Flag	Result
--set <name>=<value>	Bind a writ placeholder. Repeat the flag for more values.
--mode enforce	Block calls outside the MCP grant. This is the default.
--mode observe	Record the Writ result and forward calls that do not violate an organization rule.
--remote <url>	Connect a remote MCP Streamable HTTP endpoint.
--token-env <name>	Read the remote bearer token from this environment variable.
--header-env <header>=<name>	Read one remote header value from an environment variable. Repeat as needed.

Record and policy behavior

Standard output carries MCP messages. Record output uses standard error. The stored record includes tool requests, decisions, and visible results. Built-in secret redaction runs before storage.

A configured organization policy also applies. A project MCP grant can narrow the organization tool list. It cannot widen it. An organization approval can satisfy its matching approval rule. It cannot satisfy a Writ grant denial.

The proxy does not see model iterations, model cost, or hidden tool effects. Use writ issue when Writ must run the model and tools.