app.yaml

Lunar.dev’s app.yaml file defines core MCPX settings, including authentication, environment variables, and tool customizations. It is typically located at mcpx-server/config/app.yaml, but a custom path can be provided using the APP_CONFIG_PATH environment variable.

Authentication

Authentication can be enabled to restrict access to your MCPX server. When enabled, MCPX expects an API key to be included in incoming requests. This key is provided via the x-lunar-api-key header and must match the value set in the AUTH_KEY environment variable.

Tool Customization

Tool customization allow you to define child tools that wrap existing services with preset behaviors or fixed parameters. This is useful for creating safer or more predictable tool usage patterns, especially in the context of AI agents.

You can:

• Define child tools with custom names and descriptions.
• Append to or rewrite descriptions to clarify behavior.
• Override specific parameter values to enforce constraints.

This mechanism ensures that AI agents cannot override restricted settings and provides a cleaner experience for end users.

Usage Tips

• Use authentication to secure access to your MCPX server.
• Leverage environment variables to control your MCPX usage.
• Create child tools for safer and more agent-compatible tool invocation using toolExtensions.

Template

  permissions:
    base: # required. value can be "allow" or "block" 
    consumers:
      developers:
        base: # required. value can be "allow" or "block" 
        profiles: #optional, gets an object
          allow: #optional. expects a list of strings of profiles that are allowed
            - profile1 # example. This needs to correspond to tool group name
            - profile2
          block: #optional. expects a list of strings of profiles that are blocked
            - profile3
      my-consumer-tag:
        base: # required. value can be "allow" or "block" 
        profiles: #optional. gets an object
          allow: # optional. expects a list of strings of profiles that are allowed
            - profile2
          block: # optional. expects a list of strings of profiles that are blocked
  toolGroups:
    - name: profile1 # name of the tool group that corresponds to a profile in permissions
      services: 
        serviceName1: # name of the service. This is dynamic and created by the user. 
          - myTool1 
          - myTool2
        serviceName2: "*" # the user can use a * to signify all the tools in one service 
  auth:
    enabled: # required. boolean "true" or "false"
    header: # optional string. This corresponds to the header from where to get the auth key. 
  toolExtensions:
    services: 
      serviceName: #name of the service (dynamic, can be what the user chooses)
      serviceName2: 
        childTools:
          - name: childToolName
            description: #optional
              action: # "append" or "rewrite" 
              text: "description of child tool"
            overrideParams: #record tin which each value is a string, a number, or a boolean
              my-param1: 8
              my-param2: "string"
              my-param3: true