Access Control List (ACL)

It is possible to define global-level, service-level and/or tool-level access control, per consumer.

MCPX will extract the x-lunar-consumer-tag header in order to identify the consumer group of the client. See MCPX Consumer Tags for more information about passing headers.

Tool Groups

In order to define tool groups, the top-level toolGroups field is used. It expects an array of objects, each containing a name (string) and services, which is a map of MCP server names (corresponding to those that were defined in config/mcp.json). Per service, you can either refer to all the its tools by passing an asterisk (the literal string "*"), or to specific tools within this service, by listing their names in an array of strings.

Let's examine a possible config/app.yaml for example:

permissions:
  base: "block"
  consumers:
    developers:
      base: "allow"
      profiles:
        block:
          - "admin"
    marketing:
      profiles:
        allow:
          - "reads"

toolGroups:
  - name: "writes"
    services:
      slack: # marks specific tools from this service
        - "post_message"
        - "post_reaction"
      gmail: # marks specific tools from this service
        - "send_email"
        - "send_attachment"
      github: "*" # marks all the tools from this service

  - name: "reads"
    services:
      slack:
        - "read_messages"
        - "read_comments"
      gmail:
        - "read_email"
        - "read_attachment"

  - name: "admin"
    services:
      slack:
        - "create_channel"
        - "delete_channel"

In this YAML definition, we declare that:

• Globally, by default, no tools or services discovered by MCPX are allowed (by setting permissions.base to block). This will be applied to any consumer (x-lunar-consumer-tag header, as described above) that is not one of the two declared ones: developers or marketing.

• Next, we may specify consumer-level permissions:

  • For consumers identifying as developers, the base permission is changed to allow - meaning, any tool or service discovered by MCPX would be available to them, unless excluded explicitly.
  • On the contrary, for consumers identifying as marketing, the base permission is not overridden, hence it remains block.

• Within each consumer-level permission declaration, we may exclude or include specific tools/services:

  • For developers, we exclude the tool group labeled as admin. That means that, effectively, they can use any tool or service discovered by MCPX except for that group.
  • For marketing, we include the tool group labeled as reads. That means that, effectively, they can use only tools or services declared in that group.
  note

  MCPX ACL feature currently works under the premise that there are no malicious actors within the system - that is, that consumers will not try to falsely identify themselves as other consumers in order to gain further controls. In that sense, MCPX ACL feature does not replace classic authentication flows. However, it does allow scoping of abilities into easily declared groups.