Back to Browse

Asana Gate MCP Server

Business ToolsLow Risk10.0MCP RegistryLocal
Free

Server data from the Official MCP Registry

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

About

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

Security Report

10.0
Low Risk10.0Low Risk

Valid MCP server (3 strong, 0 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry. Trust signals: trusted author (3/3 approved); 5 highly-trusted packages.

10 files analyzed · 1 issue found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

file_system

Check that this permission is expected for this type of plugin.

HTTP Network Access

Connects to external APIs or services over the internet.

What You'll Need

Set these up before or after installing:

The Asana Personal Access Token the gate works with; not needed when one is saved with `asana-gate token set`.Required

Environment variable: ASANA_ACCESS_TOKEN

The policy file to enforce; by default the project's .asana-gate/policy.yaml, else ~/.asana-gate/policy.yaml.Optional

Environment variable: ASANA_GATE_POLICY

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "asana-gate": {
      "command": "npx",
      "args": [
        "-y",
        "asana-gate@0.4.1"
      ],
      "env": {
        "ASANA_GATE_POLICY": "your-asana-gate-policy-here",
        "ASANA_ACCESS_TOKEN": "your-asana-access-token-here"
      }
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

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
    
  2. 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
    
  3. 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
    
  4. 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

KeyMatchesLevel
(none)the whole workspace0
teamthe team and every project in it1
portfoliothe portfolio, its nested portfolios, and every project in them1
unhomed: truetasks that belong to no project (and inherit none from a parent task)1
projectthe project and everything in it2
sectiona section of the project given alongside (a section gid needs no project)3
subtreea task (gid) and all of its subtasks, recursively4
taskexactly that task (gid)5
tagfilter: tasks carrying the tag+
assigneefilter: tasks assigned to me, a gid or an email+
custom_fieldfilter: tasks whose field (by name or gid) holds one of the values, e.g. { Owner: AI }+
created_byfilter: tasks created by me, a gid or an email+
completedfilter: completed (true) or open (false) tasks+
has_parentfilter: subtasks (true) or top-level tasks (false)+
namefilter: tasks whose name satisfies prefix, suffix, contains or matches (a regex)+
overduefilter: tasks whose due date has passed (true) or not (false)+
due_withinfilter: tasks due within a duration from now, such as 7d+
created_withinfilter: tasks created within a duration, such as 24h+

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 where the object they belong to does. Stories, attachments and time entries follow their task (a story on a goal and an attachment on a project brief follow that instead); sections, project briefs, task templates and project memberships follow their project; status updates and memberships follow their project, portfolio or goal, and allocations, budgets and rates their project or portfolio. A webhook follows the object it watches, which may be a task or a team as well. Project templates and team memberships follow their team, as does a goal that has one, and a goal relationship follows the goal it supports. Tags, users, custom field definitions, tables, records and most administrative resources live at workspace level.

Actions

An action is <resource>:<verb>. 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.

ResourceVerbs
taskread create update delete complete move add_project remove_project set_parent assign
story project_brief goal goal_relationship membershipread create update delete
attachmentread create delete
sectionread create update delete reorder
projectread create update delete archive manage_members
portfolioread create update delete manage_members
status_updateread create delete
tagread create update delete apply
custom_field allocation budget rate role record table ooo_entry time_tracking_category time_tracking_entryread create update delete
custom_field_settingread create delete
project_templateread create delete
task_templateread delete
teamread create update manage_members
workspaceread update manage_members
user notification project_portfolio_settingread update
access_request timesheet_approval_statusread create update
webhookread create update delete
organization_exportread create
exportcreate
ruletrigger
project_membership portfolio_membership team_membership workspace_membership user_task_list custom_type job event audit_log ai_studio_usage agent time_period reactionread

read is the prerequisite of every other verb: an object whose read is not allowed is invisible, whatever else a rule says.

Some verbs are implied by the request body: updating a task's completed needs task:complete, and so does the approval_status of an approval task, which Asana keeps in step with it (a new approval task in a status other than pending counts as completed, too); its assignee needs task:assign, a project's archived needs project:archive; every other member needs update. A custom field defined in place where one is put on a project, a portfolio, a goal or a table is created by that request, so it needs custom_field:create in the workspace as well, and the constraints on custom_field shape the definition. One named by gid must be visible to the policy, like any object a request names, to be put on and to be taken off; so must the table a new record goes into, and the tables a record search filters by. Taking a local field off again (one outside the workspace's library, as a field defined in place on a project is) deletes it, as live checks showed, so that needs custom_field:delete as well; a library field needs only custom_field_setting:delete.

Explicit-only actions move data out of Asana or out of asana-gate's control, so no group or wildcard grants them; a policy must spell them out: webhook:create, webhook:update, export:create, organization_export:create, organization_export:read, audit_log:read. Asana restricts some operations further on its own side, and the gate passes its answer through: audit log events, workspace events, organization exports and graph exports are served only to a service account of an Enterprise-tier organization, task templates, allocations, rates and custom roles take a paid tier, and the early-access Agents endpoints answer only requests that carry the ai_teammate_actors flag, which asana.enable in the settings sends. Where a policy restricts rather than grants (deny, confirm, limit), groups and wildcards do cover them, so deny: [modify] also refuses webhook:create there.

fields

fields on a rule grants <resource>:update limited to the listed members (plus the verb a member stands for, such as task:complete for completed). An update that touches any other member is refused with a 403 naming the member. A task's dependencies and dependents, which their own operations change (addDependencies, removeDependents, …), may be listed too. It applies to updates only; creating an object is governed by create alone.

Constraints

Besides allowing and denying actions, a rule can constrain the requests made in its scope and the responses they get: what a member must look like, what is filled in, what may not be set, what is hidden, how often an action may run and what a person must confirm. A rule may consist of constraints alone, without allow or deny; its where decides where they are in force.

rules:
  - where: { project: "AI backlog" }
    allow: ["task:*", story:create]
    require:
      task:
        name: { prefix: "[AI] ", max_length: 80 }
        due_on: { present: true, min: today, max: "+30d" }
        custom_fields: { Owner: { in: [AI] } }
    apply:
      task:
        name: { prefix: "[AI] " }
        tags: { add: [ai-generated] }
        custom_fields: { Owner: AI }
    forbid: { task: [html_notes, followers] }
    redact: { task: [notes] }
    limit: { "task:create": { max: 20, per: 1h } }
    confirm: [task:delete, "project:*"]
ClauseActs onMeaning
requirecreate and update requestsper resource and member, what the value must satisfy; a request that does not is refused with a 400 naming every problem
applycreate and update requestsper resource and member, what is filled in or rewritten before the request reaches Asana
forbidcreate and update requestsper resource, members the request may not set
redactresponsesper resource, members removed from every object the agent sees
limitactionsper action, at most max requests per per (30m, 24h, 7d); the next one is refused with a 429
confirmactionsactions a person must confirm before they run: 428 when nobody can be asked, 403 when they decline

Members are the request members of Asana's API (name, due_on, assignee, projects, tags, …); a member Asana does not accept for the resource is an error when the policy loads. custom_fields nests by field name or gid, and the values of an enum field may be option names or gids; a field named like an operator (in, value, …) is named by its gid, and operators may not stand beside field names. Names in in, not_in and apply values are resolved when the policy loads, like names in where: enum option names, tag names (tags), users (me or an email for assignee, followers, owner), projects and teams. A request names them as Asana takes them, by gid (a user also by me or an email), so a refusal lists each value with its gid, as in must be one of AI (1200000000000071); apply sends the gid.

A requirement combines operators, all of which must hold:

OperatorMeaning
present: true (or just true)required when creating; cannot be cleared when updating
prefix, suffix, containsthe string must start with, end with or contain the text
matches, not_matchesthe string must, or must not, match the regular expression
min_length, max_lengthbounds on the string's length
in, not_inthe value, or every element of a list, must (not) be one of these; references compare by gid or name
min, maxbounds on a number, or on a date: YYYY-MM-DD, ISO 8601, today, now, +7d, -1d (a date-only value such as due_on is compared by calendar day, and a time without an offset is read as UTC)

An application is a bare value (a default) or an object of operators:

OperatorMeaning
defaultset when the member is absent or empty (on update, only when the request clears it)
valuealways set, whatever the request says
prefix, suffixadded to the string unless already there
addvalues a list member must contain

When several rules apply to one object, every require holds, the most specific rule's apply wins per member, and forbid, redact and confirm add up. A request is shaped in the order apply, forbid, require, so a default or a prefix can satisfy a requirement. A project, portfolio or task made from a template or as a duplicate is shaped on the members its request sets itself, as a create of its own would be (its name, and an instantiated project's team and privacy_setting); what the template or the copy brings is left to it, so a requirement on another member does not hold such a request back. Limits count per rule and action inside one gate process, over a sliding window, and a refused request does not count; they are a brake on runaway agents, not an audit trail.

How a request is decided

  1. The request is matched to one of Asana's operations, and the objects it touches are loaded from Asana to find their place: workspace, team, portfolios, project, section, parent tasks, tags, assignee, custom field values.
  2. For each action the operation needs, the most specific matching rules decide. Specificity is the hierarchy level of the scope (see the table), then the number of filters; between rules of equal specificity, deny wins. A rule that mentions neither the action nor the scope does not take part. No matching rule means deny.
  3. A task multi-homed in several projects must be allowed in every one of them; if any of its projects hides it, the task is invisible.
  4. A subtask with no project of its own takes its placement from the nearest ancestor that has one (up to five levels); failing that it is unhomed.
  5. Invisible objects answer with Asana's "Not a recognized ID" 404. Visible objects on which the action is not allowed answer with a 403 whose message starts with asana-gate:.
  6. A create or update request is then shaped by the constraints in force: apply completes it, and a member that breaks forbid or require refuses it with a 400 naming every problem.
  7. A limit that is already full refuses with a 429; an action under confirm runs only after a person confirms (428 when nobody can be asked, 403 when they decline). The order matters: a later refusal never reveals what an earlier one hides, nobody is asked to confirm a request that would be refused anyway, and a refused request does not count against a limit.
  8. Lists, searches, typeahead and events are filtered; nothing says how many items were removed (GET /projects/{gid}/task_counts is the exception: it is passed through and counts the project's hidden tasks too). A filtered page is refilled from the following pages so that it stays as full as asked for, never fuller. A limit or confirm on a read action applies to lists of that resource as well, once per request.
  9. Every object in a response carries allowed_actions, the actions the policy currently allows on it, so an agent can plan before acting; members under redact are removed. Nested references to hidden objects (a subtask's parent, dependencies, a job's new_task, …) are removed, and visible ones are redacted as their own place in the policy says.

Rule order in the file does not matter. asana-gate explain <gid> shows how the policy treats one object, which rules decided each action, and the constraints in force on it.

Several policies

The policy in force is made of up to three files: the project's .asana-gate/policy.yaml (or the file --policy points at), your own ~/.asana-gate/policy.yaml, and an administrator's managed-policy.yaml beside the managed settings. Every one of them that exists is read, and an action is allowed only when every file allows it: each file is evaluated on its own, with its own most specific rule deciding and its own default of deny, and the answers are combined with AND. So your own policy is the most you can ever do in any project, the administrator's the most anyone on the machine can do, and the project's what this project allows within those bounds; a file that does not mention an action denies it, exactly as a lone policy would. With allow: [read] in one file and allow: [task:read] in another, only tasks can be read, whichever file says which; with allow: [team:read] in one and allow: [task:read] in the other, nothing can. Constraints add up across files the way matching rules of one file do, fields allowlists intersect, and where two files apply the same member at equal specificity the stronger wins: the administrator's, then the project's, then yours. A file other than the project's may leave workspace out, and is then in force wherever the project's policy is; one that names another workspace is not in force there, which check reports. When the project has no policy, yours is the policy, bounded by the administrator's; when only the administrator's exists, it is the policy. check lists every file in force, and messages name a rule by its file when there are several (user rules[2]).

MCP server

asana-gate mcp serves the curated tools the policy could ever allow (a read-only policy lists no writing tool), plus three generic ones; the policy is applied when a tool runs. Claude Code loads tool definitions on demand once they grow large, so a long list costs little there. The server's instructions tell the agent whom every request runs as: the gid of the token's user and the name and gid of the workspace, so it can tell which assignee, created_by or followers in a response is itself; the user's name and email are added only as far as the policy would show them through GET /users/me (workspace:read and user:read at workspace level, then redact).

  • Curated tools for everyday work: asana_search_tasks, asana_list_tasks, asana_get_task, asana_create_task, asana_update_task, asana_create_comment, asana_move_task_to_section, asana_add_tag_to_task, asana_list_projects, asana_create_section, asana_typeahead, asana_get_me and more.
  • asana_create_tasks and asana_update_tasks take up to 50 tasks at once, asana_create_records and asana_update_records as many records: the gate checks each one, Asana runs them ten at a time, and the result holds one status per task or record.
  • asana_get_task answers the task's latest comments and its direct subtasks in the same call when asked (include_comments, include_subtasks), and asana_get_project its sections and task counts (include_sections, include_task_counts): each part is a request of its own to the gate, and one the policy or Asana refuses is null.
  • asana_request calls any REST operation (method, path, query, body) through the same policy; a POST /batch through it takes up to 50 actions.
  • asana_operations lists the operations with the action each one needs; asana_allowed_actions tells what the policy allows on one object.

Refusals come back as tool errors whose text is the JSON error body, so agents see the same wording a direct API client would. A tool refuses an argument its input does not declare, naming it, rather than run without it; asana_request takes every member of an operation.

Confirmations

When a rule's confirm covers the action, the server asks the person through MCP elicitation before the call runs; nothing reaches Asana until they say yes. On a connection that negotiated the 2026-07-28 protocol revision the tool call answers with an input_required result carrying a form elicitation and a sealed requestState; the client shows it and resends the same call with the answer and the state, which the server checks before executing, so an answer counts only for the question this server asked, about the call with these very arguments. On an older connection the server sends elicitation/create itself and waits up to ten minutes for the answer. A declined or cancelled confirmation refuses the call with a 403. A client that does not implement elicitation cannot confirm, so the action does not run (428). Over the HTTP transport an older client is served one request at a time and cannot receive elicitation/create, so confirmations there need a client on the 2026-07-28 revision.

Transports

asana-gate mcp                         # stdio (default)
asana-gate mcp --transport http        # Streamable HTTP on http://127.0.0.1:3845/mcp
asana-gate mcp --transport http --host 0.0.0.0 --port 8080 --allowed-host gate.example.internal

The HTTP transport validates Host and Origin headers against loopback plus --allowed-host entries (DNS rebinding protection). Binding to anything but loopback requires a bearer token in ASANA_GATE_MCP_TOKEN (or the variable named by --auth-token-env), which clients must send as Authorization: Bearer ….

CLI

asana-gate mcp                     Serve the policy-gated Asana API as an MCP server
asana-gate check                   Validate the settings, the token and the policy against Asana
asana-gate explain <gid>           Show what the policy allows on one object, and why
asana-gate init                    Create the project's .asana-gate directory; --agent claude-code wires Claude Code
asana-gate token                   Show where the Asana token comes from, or save one (never printed)
asana-gate settings                Show the settings in force and where each value comes from
asana-gate cache                   Show or clear the on-disk cache of workspace names
asana-gate <resource> <verb> …     Operate Asana through the policy
asana-gate api <METHOD> <path>     Call any Asana REST operation through the policy

Common options: -C <dir> (run as if started in <dir>), --policy <file> on the commands that read a policy (default: the project's .asana-gate/policy.yaml, see Configuration), --token-env <NAME> (default ASANA_ACCESS_TOKEN), --log-level silent|error|warn|info|debug. check fails (exit code 1) on a problem, such as an object the policy names that no longer exists, and only warns about the rest. init and explain read Asana without the policy's restrictions; they exist to write policies and are not reachable over MCP. explain also prints the constraints in force on the object.

Operating Asana from a shell

Every curated MCP tool is also a <resource> <verb> command with the same inputs, so whatever an agent may do over MCP, a person may do from a shell under the same policy.

asana-gate task list --project 1200000000000123 --completed-since now
asana-gate task create --name "Write docs" --projects 1200000000000123 --due-on 2026-12-01
asana-gate task update 1200000000000456 --assignee me --completed
asana-gate task move 1200000000000456 --section 1200000000000789
asana-gate task comment 1200000000000456 --text "Done, see the attached diff."
asana-gate task delete 1200000000000456
asana-gate task create-many --tasks @tasks.json
asana-gate section create --project 1200000000000123 --name "Review"
asana-gate find design --type project
asana-gate api GET /tasks/1200000000000456 -q opt_fields=name,completed
asana-gate api POST /tasks -d '{"name": "Write docs", "projects": ["1200000000000123"]}'
  • The object a verb acts on is a positional argument; everything else is a flag named after the API member (--due-on for due_on).
  • Booleans are switches (--completed, --no-completed); lists take comma-separated values or repeated flags; --custom-fields, --tasks and other objects take JSON, inline, from a file (@tasks.json, relative to -C) or from standard input (-); null clears a member that allows it.
  • Lists print as tables with a hint for the next page, objects as key: value lines; --json prints the response body as Asana returns it, which api always does.
  • When the policy wants an action confirmed, the command asks on the terminal; --yes (-y) confirms in scripts, and a non-interactive run without it is refused.
  • Exit codes: 0 on success, 1 when Asana or the policy refuses the request, 2 for a usage error.
  • A limit counts inside one process, so it binds the MCP server; one-shot commands start from zero each time.
  • asana-gate <resource> --help lists the verbs; asana-gate <resource> <verb> --help lists the flags, with what is required and what the choices are.

Logs go to stderr and, by default, to ~/.asana-gate/logs/asana-gate.log (log.file in the settings). The token is never written to logs, errors, URLs or responses. At info level the client also reports the API changes Asana announces in its Asana-Change response header.

Configuration

asana-gate keeps its files the way Claude Code does: a .asana-gate directory in the project, one in your home directory, and settings an administrator can manage.

Documentation truncated — see the full README on GitHub.

Reviews

No reviews yet

Be the first to review this server!