oakallow governance skill

oakallow is a hosted remote MCP server that sits between an agent and the actions it wants to take. For direct tools it does not run your tools or receive your tool parameters; for OakGuard gateway tools it forwards approved calls without storing them. It governs the moment of execution: it checks whether a specific action is permitted, gates risky or irreversible actions behind human approval, and records an immutable audit row.

This skill tells you, the agent, when and how to call oakallow's tools so a governed workflow behaves correctly.

• Endpoint: https://api.oakallow.io/mcp (Streamable HTTP)
• Authorization: self-hosted OAuth 2.1 (PKCE, S256) for human-driven clients, or an oak_agent_ bearer token for autonomous agents (both on the same endpoint)
• Website: https://oakallow.com
• Scopes: mcp:read (list, check, read activity), mcp:write (create approval requests)

Account and authorization (read this first)

oakallow is hosted and requires an oakallow account. You cannot use this connector anonymously.

• Connecting runs an OAuth 2.1 flow. The host opens oakallow's hosted consent

screen, the human signs in to their oakallow account, and approves the scopes (mcp:read, mcp:write). Authorization is bound to that signed-in account.

• Humans define and decide everything that governs you. In the oakallow

dashboard, a person registers the tools an agent may use, sets the permission rules for each tool, decides which actions require approval, and approves or denies requests. The connector does not configure tools or set rules, and it can never approve on a human's behalf.

• If there is no valid oakallow session, the connector cannot be used until the

human signs in. Surface that to the user rather than trying to work around it.

• Autonomous agents that run with no human to sign in use a pre-issued

oak_agent_ bearer token instead of the OAuth flow (Authorization: Bearer oak_agent_...). The token is scoped to one org and the agent can submit and check requests but never approve, the same governance still applies. A person provisions it from the dashboard; see https://oakallow.io/info/agents.

The mental model

oakallow is a requester and pass-through, not a decider. The connector can ask whether something is allowed and can request approval, but it can never approve or deny on a human's behalf. Decisions happen on a separate, MFA-bound surface (the oakallow dashboard or mobile app). So the agent's job is:

1. Before a sensitive action, ask oakallow if it is allowed.
2. If it requires approval, request it, then wait for a human to decide.
3. Once a human approves, perform the action.
4. Every outcome is recorded in an immutable audit row.

Never assume an action is allowed. Never try to self-approve. Never route a decision through the connector.

Tools

Targeting the right organization

An oakallow account can have more than one organization, and each org has its own tools, rules, approvers, and alerting. So a check must go to the org the action actually belongs to.

check_permission and list_my_tools take an optional `org` argument: the org's external id (org_oak_…):

• If the account has exactly one org, omit it.
• If the account has more than one org, pass `org`. This skill is downloaded

per-org from the oakallow dashboard, so the org id for the org this skill governs is stated below. Pass that id on every check_permission call. If you omit it on a multi-org account, the call is refused rather than sent to the wrong org.

You cannot list orgs through the connector and you cannot reach an org you do not have access to. Passing an org id you lack access to is refused. The org id comes from this skill (downloaded for that specific org), not from probing.

`check_permission` is a dry-run. It returns a read-only verdict (allowed / requires_approval / disabled; treat blocked, if you see it, exactly like disabled) and nothing else. It does NOT create an approval request and does NOT return a reference (REF-…). The approval and its REF-… are created later, when you call the gated tool itself through oakallow (see the workflow below). One side effect to know: checking a tool oakallow has never seen is intentionally not a no-op: oakallow auto-creates a gated draft entry for that tool with conservative, fail-closed defaults so the eventual call is governed and the owner can triage it. An unknown tool is never silently trusted, so do not call check_permission speculatively on tools you have no intention of using.

Core workflow: a governed action

Follow this sequence whenever you are about to take an action that affects another system or could be risky or irreversible.

1. (Optional) `check_permission` for the action, passing the `org` id

this skill names (see "Targeting the right organization"). This is a dry-run: it returns a verdict only and creates nothing.

• allowed then the action is permitted without approval, so perform it

(step 5).

• requires_approval then it is gated, so go to step 2 to create the approval.
• disabled / blocked then do not perform the action; surface the reason and

stop. Do not look for a workaround.

1. Create the approval: call the gated tool itself through oakallow, passing

the `org` id, a clear `reason`, and your `agent` id (see "Arguments on governed tools"). For a direct tool, oakallow does NOT execute it. When it is gated, oakallow creates the approval request, notifies a human, and returns a requires_approval response carrying a reference (`REF-…`). This call is what mints the reference; there is no separate "request approval" tool. (If it returns allowed, the action was permitted, so perform it. If disabled/blocked, stop.)

1. Wait for the human. Tell the user an approval was requested and that a

human approver must decide in the oakallow dashboard or app under enforced MFA. Note the `REF-…` returned in step 2.

1. `check_approval_status` using that reference to poll. Poll politely and do

not hammer it. When the status resolves:

• approved then perform the action.
• denied then do not perform the action. Report the denial, and the reason

if one was given, to the user.

• expired then the request timed out without a decision. Do not perform the

action; offer to re-request if the user still wants it.

1. Perform the action. For a direct tool, run it on the customer's own

system/connector (oakallow does not execute customer tools). For an OakGuard gateway tool, call the same tool through oakallow again: oakallow claims the approval and forwards the call to the customer's MCP server. Either way, each approval authorizes exactly one execution, and oakallow records an immutable audit row for the outcome.

Arguments on governed tools

Customer-defined tools appear in tools/list alongside the four standard tools. A direct tool accepts two optional arguments; an OakGuard gateway tool accepts its real downstream arguments plus the same oakallow fields:

• `reason`: a short, non-sensitive summary of why you are calling it. This is

what the human approver reads (see below). oakallow redacts SSN, card, email, phone, and address patterns before storing it, but do not rely on that.

• `agent`: an identifier for you, the calling agent (a name or code). It lets

the org's governance report show which agent submitted each call instead of attributing everything to the signed-in account. Send the same value on every call. When you authenticate with an oak_agent_ token, the token's own identity is used and this argument is ignored.

• `org`: the org id this skill names, as described above.

Signed decision receipts

Every permission decision on an approved tool, whether allowed, requires_approval, or disabled, comes back with a signed decision receipt reference (an HMAC-signed record of what oakallow decided about this exact request, stored for later verification). If oakallow cannot sign or record the decision, the check fails closed: you get no verdict rather than an unproven one. Surface the receipt reference to the user alongside the outcome; it is how they can later prove what was allowed or blocked.

OakGuard gateway tools

An org can register its own MCP servers with oakallow (OakGuard). Their tools show up in tools/list under their real names and schemas, and oakallow becomes the transport to them: a call is forwarded to the downstream server only after the permission check says allowed or a human has approved the REF-…. oakallow passes the request and response through over TLS but does not store or log them. Govern these exactly like any other tool; the only difference is step 5 above.

Writing the approval reason

When an action requires approval, the human approver sees a reason. Make it genuinely useful, because it is what a person uses to decide in seconds:

• State what action you want to take and on what (the target or resource).
• State why, meaning the user request or investigation that led here.
• Keep it concise and factual. No secrets, no raw credentials, no full tool

parameters. oakallow only carries a PII-scrubbed reason by design, so do not try to smuggle sensitive payloads into the reason text.

Good: "Restart the production payments-api service on host db-3 to clear a stuck worker queue the user reported at 14:02."

Bad: "Do the thing", or pasting an API key or full request body into the reason.

Checking on outstanding work

• Use `list_pending_approvals` to show the user everything currently awaiting

a human decision, which is useful when resuming a session or when the user asks "what is waiting on me?".

• Use `check_approval_status` with a specific reference to poll one request.

Rules of thumb

• Ask before acting on anything risky, irreversible, or cross-system.
• Respect `disabled` and `denied`. Never seek a workaround and never retry to

get a different answer.

• Never self-approve or treat the connector as a decision surface. Humans

decide in the dashboard.

• Do not speculatively `check_permission` tools you will not use, because it

creates gated draft entries that the org owner then has to triage.

• Be transparent with the user about what was checked, requested, approved,

denied, or blocked, and surface the REF-… and the decision receipt.

Example: end to end

User: "Delete the abandoned staging-old database."

>

1. Agent calls check_permission for delete_database (dry-run). The verdict is requires_approval. Nothing has been created yet. 2. Agent calls the gated delete_database tool through oakallow with reason: "Delete abandoned staging-old database at user's request" and its agent id. oakallow creates the approval request, notifies a human, and returns a REF-… plus a signed decision receipt. 3. Agent tells the user: "That is a destructive action, so I have requested approval (REF-…). A human needs to approve it in oakallow." 4. Agent polls check_approval_status with the REF-… until it resolves. 5. On approved, the agent performs the delete once and reports completion. oakallow writes the audit row.