asana-gate

asana-gate

A declarative access-control policy in front of the Asana REST API, served to AI agents over MCP.

MCP client ──MCP──▶ asana-gate ──policy──▶ Asana REST API

You give an agent a Personal Access Token through asana-gate instead of directly. A policy file then decides, per project, section, task, tag or assignee, what the agent can see and do. Everything else does not exist for the agent.

Why

An Asana token grants everything its owner can do. Agents need much less: read this team, update tasks in that project, never touch the Done section, never delete. asana-gate turns such sentences into a YAML file and enforces it on every one of Asana's REST operations.

• The policy is the only source of permissions. The token's rights are an upper bound; the default is deny.
• Invisible, not forbidden. Objects the policy hides answer exactly like nonexistent gids (a 404 with Asana's own wording), and never appear in lists, searches, typeahead or events.
• Every endpoint is covered. Every operation of Asana's OpenAPI definition is classified. A plain read, update or delete of one object (GET /tasks/{task_gid}) is classified from its path; any other operation Asana adds fails the build until it is classified, and the weekly OpenAPI report names every new one for review, so none passes through unreviewed.
• MCP as specified. stdio and Streamable HTTP transports, no client-specific extensions.

Install

npm install -g asana-gate

Node.js 24 or later is required. npx asana-gate works too. The server is listed in the MCP Registry as io.github.sincekmori/asana-gate, for the clients and catalogs that read it.

Quick start

1. Create a Personal Access Token and give it to asana-gate: exported for this shell, or saved in your home directory in a file only you can read (it is never printed).

   export ASANA_ACCESS_TOKEN="…"   # this shell only

asana-gate token set --user # or keep it in ~/.asana-gate/token, typed unseen or piped in

1. Let asana-gate look at your workspace and create the project's .asana-gate directory: a policy skeleton, a settings file and a .gitignore that keeps personal settings and the token file out of git.

   asana-gate init

1. Edit .asana-gate/policy.yaml, then validate it: names are resolved against Asana, every gid the rules name is checked to exist, and the token is checked.

   asana-gate check

1. Serve it to your MCP client.

   asana-gate mcp

For Claude Code, asana-gate init --agent claude-code writes the project's .mcp.json, a copy of the skill and a permission rule that keeps the token from the agent (see Agents). For any other MCP host, register the command; started inside the project directory, asana-gate mcp finds the policy and the token by itself, and -C points it at the project when the host starts it elsewhere:

   {

"mcpServers": { "asana-gate": { "command": "npx", "args": ["-y", "asana-gate", "mcp", "-C", "/path/to/project"] } } }

Policy

A policy names one workspace and lists rules. Each rule has a scope (where), the actions it allows or denies there, and optionally constraints on the requests made there.

version: 1

workspace: "1200000000000001" # a gid or a name

rules:

No where: the whole workspace. Read everything.

• allow: [read]

Everything a team owns is writable (create and update, no delete).

• where: { team: "Platform" } allow: [write]

Full task work in one project, plus comments and tags.

• where: { project: "1200000000000123" } allow: ["task:*", story:create, tag:apply]

...but its Done section is frozen (still visible; deny: ["*"] would hide it).

• where: { project: "1200000000000123", section: "Done" } deny: [modify]

Tasks tagged ai-ok may be updated wherever they are already visible.

• where: { tag: "ai-ok" } allow: [task:update]

Read a project, and update only these task fields in it.

• where: { project: "Design System" } allow: [read] fields: { task: [completed, assignee, due_on] }

Tasks created here get a prefix and a tag, must have a due date,

are capped at 20 an hour, and are deleted only after a person confirms.

• where: { project: "AI backlog" } allow: ["task:*"] require: { task: { due_on: true } } apply: { task: { name: { prefix: "[AI] " }, tags: { add: [ai-generated] } } } limit: { "task:create": { max: 20, per: 1h } } confirm: [task:delete]

Hide a project completely.

• where: { project: "Payroll" } deny: ["*"]

Names are resolved to gids when the policy loads; an unknown or ambiguous name is an error. Gids always work. Every scope key accepts one value or a list (any of them matches).

Scopes

Hierarchy keys in one where are ANDed. Filters (tag, assignee, custom_field and the state filters below them) are ANDed with the hierarchy keys and never make an object visible on their own: they narrow or widen what may be done with objects that another rule already lets the agent read, and they may hide objects (deny: [task:read]). For a create request, the filters see the object the request would create: its name after apply, the token's user as its creator, its due date and so on.

Objects that are not tasks live at the nearest hierarchy level: stories, attachments, time entries and the like follow their task; sections, briefs, status updates, memberships, templates and webhooks follow their project, portfolio or goal; tags, users, custom field definitions and most administrative resources live at workspace level.

Actions

An action is : . Groups and wildcards expand to concrete actions: read (every read), modify (every other verb, the complement of read), write (read plus every creating and modifying verb), admin (everything), * (same as admin), task:*, *:delete. A rule takes part only for the actions it names, so a scope is made read-only with allow: [read] and deny: [modify] together: the deny keeps a broader allow elsewhere from reaching it, and unlike deny: ["*"] it leaves the objects visible.

| custom_field allocation budget rate role record table ooo_entry time_tracking_category `time_tracking_entr